DEV Community: Dawid Nitka

Save 60-90% of Your Claude Code Tokens With Two Tools

Dawid Nitka — Tue, 16 Jun 2026 01:44:22 +0000

TL;DR: Two tools cut Claude Code token usage at two different layers. RTK is a shell proxy that compresses command output before it ever reaches the context window. context-mode is a Claude Code plugin that does heavy tool work in a sandbox and hands back only the answer. They stack cleanly on top of each other, and a single skill installs both. This article explains how each one works and how to wire them in.

Two commands into a session, my context window was already a third full, and I hadn't written a line of code yet. A pnpm install had dumped its entire dependency tree, a git log paid out two hundred commits, then a stack trace landed in full. None of that was work I'd asked for - it just sat there in the context window eating tokens on every turn.

Most of the token budget goes on that boring output - the installs, the logs, the traces - which piles up and gets re-read on every single turn, never on the clever reasoning you actually wanted. Two tools attack that pile from two directions. Here's how they work, and how to install both in one command.

This is the last article in the series, and it builds on the skill pattern from the third. You can pass this article URL straight to Claude Code and follow along.

Where the tokens actually go

Picture the context window as a desk. Everything Claude needs stays on the desk so it can glance at it: your prompts, its replies and the output of every command it ran. The desk has a size limit, and once something is on it, it gets re-read on every turn until it falls off the edge.

Two kinds of clutter land there:

Command output that arrives bloated. A dependency install, a long log, a verbose test run. It enters once and costs tokens on every turn after.
The accumulated pile itself. Even reasonably sized outputs add up across a long session until the desk is buried.

The two tools map onto those two problems. RTK trims the output before it ever reaches the desk. context-mode keeps the heaviest work off the desk altogether.

Layer 1: RTK, trim it before it lands

RTK is a shell-level proxy. It sits between Claude and the commands it runs, intercepts the output and compresses it before it reaches the context window. The claim is 60 to 90 percent savings on typical dev operations, and it ships a rtk gain command so you can check your real number instead of taking the claim on faith.

The mechanism is a hook. After you set up the Claude Code integration, every Bash command Claude runs gets transparently rewritten to route through RTK. git status becomes rtk git status behind the scenes, with no change to how you or Claude write commands and no token overhead for the rewrite itself.

Install is two moves: drop in the binary, then wire the integration.

# after installing the binary (follow the README for your platform)
rtk init -g

Then confirm it's the right tool and it's working:

rtk --version
rtk gain

One trap worth naming: there's a second, unrelated project that also ships a binary called rtk (a Rust type toolkit). If rtk gain comes back "command not found" after a clean install, you almost certainly have the other one. Check with which rtk and grab the token-killer from its own repo.

Layer 2: context-mode, keep it off the desk

context-mode comes at the problem from the other side. It's a Claude Code plugin, MCP server plus hooks, and instead of trimming output it relocates the heavy work.

When Claude needs to process something large - a big log, or a sprawling JSON payload - context-mode runs that work in a sandbox and returns only the derived answer. The raw bytes never enter the context window. You asked how many errors are in a 10,000-line log, you get back "47" and the breakdown, not the log. The desk stays clear because the bulky part of the job happened in the magic drawer.

Because it registers an MCP server and hooks, context-mode only activates after a full restart of Claude Code. Installing it is the usual two plugin commands:

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Restart, then verify it came up:

/context-mode:ctx-doctor

The shortcut: one command for both

Installing two tools by hand, across platforms, with steps that drift as the projects evolve, is exactly the kind of chore Article 3 argued you should automate. So this is a skill too.

The catch is that install steps go stale. Hardcode them today and the article rots the moment either project changes a flag. So the skill doesn't hardcode anything. It fetches the current README for each tool at run time and follows whatever the install section says right now.

---
name: setup-token-savings
description: Install RTK and context-mode to cut token usage
disable-model-invocation: true
---

## Instructions

### Step 1 - Fetch latest install instructions

Use WebFetch to read the current README for each tool, and follow its
Installation section to check the steps below:

- RTK: https://github.com/rtk-ai/rtk
- context-mode: https://github.com/mksglu/context-mode

### Step 2 - Install RTK

Follow the RTK README for the current platform (detect with `uname -s` /
`uname -r`), then run `rtk init -g`. Verify with `rtk --version` and `rtk gain`.

### Step 3 - Install context-mode

Follow the context-mode README. Typically:
claude plugin marketplace add mksglu/context-mode
claude plugin install context-mode@context-mode

### Final step

Tell the user to fully restart Claude Code, since context-mode's MCP server and
hooks only activate on restart. Then suggest /context-mode:ctx-doctor to verify.

Drop that into skills/setup-token-savings/SKILL.md, and a fresh machine gets both tools with one command:

/your-plugin:setup-token-savings

A slightly more verbose version lives in the reference repo, in the base plugin's skills: github.com/Nagell/claude-marketplace.

Check what you saved

The point of rtk gain is that you don't have to trust the headline number. It reports your actual savings from real usage:

rtk gain            # total savings so far
rtk gain --history  # per-command breakdown

My result after some time

RTK Token Savings (Global Scope)
════════════════════════════════════════════════════════════
Total commands:    1539
Input tokens:      1.3M
Output tokens:     257.6K
Tokens saved:      1.0M (80.0%)
Total exec time:   57m58s (avg 2.3s)
Efficiency meter: ███████████████████░░░░░ 80.0%

By Command
────────────────────────────────────────────────────────────────────────
 #   Command                   Count   Saved    Avg%    Time  Impact
────────────────────────────────────────────────────────────────────────
 1.  rtk find                     95  284.0K   62.5%   33.2s  ██████████
 2.  rtk lint eslint               4  211.9K   99.5%    8.0s  ███████░░░
 3.  rtk curl -s https://r...      1  185.3K   99.9%   277ms  ███████░░░
 4.  rtk read                    135  154.0K   13.1%     0ms  █████░░░░░
 5.  rtk git diff HEAD -- ...      1   42.3K   85.1%    17ms  █░░░░░░░░░
 6.  rtk grep                    217   32.8K   18.6%    79ms  █░░░░░░░░░
 7.  rtk ls                      203   24.0K   62.1%     2ms  █░░░░░░░░░
 8.  rtk curl -s -X POST h...      2   11.1K   96.5%   653ms  ░░░░░░░░░░
 9.  rtk git log --all --o...      1    9.5K   94.7%    10ms  ░░░░░░░░░░
10.  rtk curl -fsSL https:...      1    7.2K   96.5%   387ms  ░░░░░░░░░░
────────────────────────────────────────────────────────────────────────

rtk discover goes one step further and scans your Claude Code history for commands that would benefit from routing through RTK but aren't yet, so you can widen the net over time.

Final thoughts

That's the whole setup. Your marketplace holds the plugins, your safety hooks catch the dangerous commands, one command installs everything on a new machine, and two more keep the token bill down. None of these pieces is big on its own. But wired together in a marketplace you own, the next new laptop costs you a couple of commands instead of a lost afternoon. If you've been following along, that starter template is the place to put it all: github.com/Nagell/claude-marketplace-template. If you missed any of the steps, check out other articles in the series.

Install Everything You Need in One Command: Claude Code Plugin Setup

Dawid Nitka — Tue, 16 Jun 2026 01:41:24 +0000

TL;DR: A Claude Code skill is a SKILL.md file Claude reads and executes. You can write one that installs your whole plugin lineup across several marketplaces, in the right order, and offers to drop your opinionated CLAUDE.md into the global config. One frontmatter line keeps it from firing on its own, so it runs only when you call it by name. This article walks through building that skill so a fresh machine goes from zero to fully set up with one command.

Setting up Claude Code on a new machine is a small ritual of forgetting. You reinstall the plugins, then realize you tried to install one before adding its marketplace. Eventually they work, except none of your global defaults are there because you never copied CLAUDE.md over. An hour later you're set up, and you've already forgotten half the plugins and skills for next time.

So I moved the whole ritual into a skill. This builds directly on the marketplace from the first article. If you haven't scaffolded one yet, start there. You can pass this article URL straight to Claude Code and follow along.

A skill is just a Markdown file

This is the part that surprises people. A Claude Code skill is just a SKILL.md file in a folder under your plugin's skills/ directory, no special DSL or script format, and Claude reads it as instructions and carries them out.

plugins/your-plugin/
└── skills/
    └── plugin-setup/
        └── SKILL.md         ← this becomes /your-plugin:plugin-setup

The folder name becomes the name you call. Everything in the file is a prompt: you write the steps in plain English, and Claude runs them when you invoke /your-plugin:plugin-setup.

If you wrote Claude Code commands a while back, this is where they went. Anthropic merged slash commands into skills, so the commands/plugin-setup.md you might once have written is now skills/plugin-setup/SKILL.md, invoked exactly the same way (the docs lay it out). A skill is the one primitive now.

That merge matters for setup in particular, because a skill can fire two ways: you call it by name, or Claude loads it on its own when a request looks relevant. The second path is the last thing you want from an installer. You don't need it kicking off because the word "setup" drifted past in some unrelated sentence. One line in the frontmatter, disable-model-invocation: true, switches the automatic path off, so the skill runs only when you type /your-plugin:plugin-setup and never decides to install your whole toolchain on a hunch.

The one below adds marketplaces, installs plugins and walks an interactive selection. You can put far more in a skill than that, and if one grows unwieldy you can split it and pull pieces into their own files.

The rest of this article builds our sample setup command (skill) piece by piece, then assembles the whole file at the end.

The flow, step by step

The skill opens with two setup lines, then does four things in order.

The setup lines handle environment quirks. When the skill runs as an agent driving the claude CLI, it prefixes those calls with unset CLAUDECODE && to dodge a nested-session error. On Windows, it makes sure CLAUDE_CODE_GIT_BASH_PATH is set in ~/.claude/settings.json (default C:\Program Files\Git\bin\bash.exe) before any shell step runs.

Then the four steps:

Ask how much to install. A clean two-option choice, everything or pick-and-choose, so the skill uses AskUserQuestion, the structured multiple-choice prompt.
Let the user choose (if they asked to). Here it deliberately skips AskUserQuestion. With several marketplaces and a dozen plugins that widget gets clumsy, so the skill prints a numbered list of plugins per marketplace group and takes a plain text reply, one group at a time, before moving on. No clicking through twenty checkboxes.
Install in the right order. The step that bites you by hand: a plugin can't install until its marketplace is registered. So the skill adds the marketplaces first, then the plugins, and only adds a marketplace if at least one of its plugins was selected. Pick nothing from a marketplace and it never gets registered.
Offer the global CLAUDE.md. The finishing touch, and the one most setups skip. More on why it's a separate opt-in below.

After the plugins land, the skill tells the user to restart Claude Code, since plugins activate on restart.

Why the CLAUDE.md step is an explicit offer

Article 1 made a point of this: a CLAUDE.md inside a plugin folder does nothing on its own. Claude Code's plugin system ignores it. So shipping your global defaults as a plugin file doesn't apply them anywhere.

The setup skill closes that gap by hand, as its final step: it offers to copy the plugin's CLAUDE.md into your global ~/.claude/CLAUDE.md. The key word is offer. Your global CLAUDE.md is personal, and silently overwriting it on a setup run would be hostile. So the skill checks first: it shows you the existing file when there is one, then lets you append, replace or skip. You opt in, every time.

What goes in your curated list

The plugin list is the body of the skill. Group it by marketplace and put a one-line description above each plugin as a comment. The skill reads those comments out when it prints the selection menu.

Treat it as a starting point you'll edit. Marketplaces in one block, plugins grouped under the marketplace they come from. Swap in the ones you actually reach for.

Full structure below. The reference repo carries my actual, longer list if you want more examples: github.com/Nagell/claude-marketplace.

The complete skill

Here's the whole thing, ready to drop into skills/plugin-setup/SKILL.md. It wires together every piece above: the agent-mode switch, the Windows path, the four steps, the CLAUDE.md offer and a starter plugin list with two marketplaces.

---
name: plugin-setup
description: Install all recommended plugins and marketplaces
disable-model-invocation: true
---

# Setup Plugins

Install recommended Claude Code plugins and marketplaces with interactive selection.

## Instructions

1. When running as an agent, prefix all `claude` CLI commands with
   `unset CLAUDECODE &&` to avoid the nested-session error.
2. On Windows, check `~/.claude/settings.json` for `CLAUDE_CODE_GIT_BASH_PATH`.
   If missing, set it (default `C:\Program Files\Git\bin\bash.exe`) and ask the
   user to confirm it before continuing.
3. **Ask install mode**: use `AskUserQuestion`. "Install all (Recommended)"
   installs everything below; "Let me choose" goes to interactive selection.
4. **Interactive selection** (only if "Let me choose"): do NOT use
   `AskUserQuestion` here. For each marketplace group, print a numbered list of
   its plugins, using the comment above each as the description. Ask the user in
   a plain text message to reply with numbers or names, or "all" / "none". Wait
   for the reply before moving to the next group.
5. **Install order**: add the marketplaces first, then install the plugins. Only
   add a marketplace if at least one of its plugins was selected.
6. After installing, tell the user to restart Claude Code.
7. **Global CLAUDE.md**: offer to save this plugin's `CLAUDE.md` to
   `~/.claude/CLAUDE.md`. If it doesn't exist, ask to create it. If it does,
   show both files and ask to append, replace or skip.

## Plugin List

### Marketplaces

```bash
/plugin marketplace add claude-plugins-official
/plugin marketplace add some-author/their-marketplace
```

### Plugins

#### claude-plugins-official

```bash
# Feature development workflow with exploration and review agents
/plugin install feature-dev@claude-plugins-official
# Composable workflow skills for brainstorming, planning, debugging and TDD
/plugin install superpowers@claude-plugins-official
# PR review agents for comments, tests and error handling
/plugin install pr-review-toolkit@claude-plugins-official
```

#### their-marketplace

```bash
# A skill you want available in every project
/plugin install some-skill@their-marketplace
```

Save it, install with your plugin, then run it:

/your-plugin:plugin-setup

The next article takes this further. Once your tooling installs in one command, the question becomes what that tooling costs you per session, and how to cut overall token usage.

Get started

Use the starter template to get a clean slate with everything pre-wired: github.com/Nagell/claude-marketplace-template.

The template gives you one empty plugin, a CLAUDE.md with sensible defaults, and a GitHub Actions workflow that handles versioning and releases automatically. Hit "Use this template" on GitHub and you're ready to add your first plugin.

If you want to see a fuller working example with multiple plugins and real hook scripts, github.com/Nagell/claude-marketplace is the reference repo used throughout this series.

Claude Code Safety: Hooks, Sandboxes, and Running Autonomously Without the Paranoia

Dawid Nitka — Tue, 16 Jun 2026 01:38:11 +0000

TL;DR: Claude Code runs Bash, which means it can run dangerous Bash. There are many ways to put guardrails around it. Four well-known ones: write your own PreToolUse hooks (lightweight, portable, yours), use the built-in /sandbox (filesystem and network isolation), run inside a Docker microVM (strongest isolation), or grab a community hook collection. This article walks through those four and ends with a copy-paste hook you can drop into any plugin.

Claude was halfway through cleaning up a build directory when it generated rm -rf with a path that resolved to my home folder. A glob expanded wrong. The command was syntactically fine and about to run.

It didn't, because a hook caught it and returned exit code 2. Claude saw the rejection and retried with a scoped path instead.

Safety tooling earns its place by catching the handful of commands that would ruin your day, without getting in the way of the hundred that wouldn't. There are many methods for this. Here are four well-known ones, from "ten lines of Bash" to "full microVM", and when each earns its place.

You can pass this article URL directly to Claude Code and follow along.

The permission model: how Claude Code decides what to run

Before the guardrails, the thing they hook into.

Every time Claude wants to use a tool, Claude Code runs it through a permission check. Bash commands get matched against your allow and deny rules. In normal mode you approve risky commands manually, one at a time.

Everyone who has run a real session knows where this goes. Approve, approve, approve, command after command, until the prompting wears you down and you flip on bypass mode just to get work done. And there's the gap. The moment you let Claude run autonomously, the manual approval step disappears, and a wrong command runs with no human in the loop.

That tradeoff is exactly why the more automated approaches exist. Instead of approving everything or nothing, they let Claude run freely and stop it only in the cases that actually matter. Hooks intercept the command and decide programmatically. Sandboxes constrain what any command can touch. They stack, so you don't have to pick just one.

Approach A: Custom hooks - the lightweight, portable option you own

A hook is a script Claude Code runs at a specific point in its lifecycle. The one you want for safety is PreToolUse: it fires before a tool executes, and its exit code decides what happens next.

Three outcomes:

Exit 0 - allow the command. Optionally print JSON with a systemMessage to warn without blocking.
Exit 2 - block the command. Whatever you write to stderr gets shown to Claude, so it understands why and can adjust.
JSON decision - print a permissionDecision object to deny with a custom reason, even in bypass mode.

You wire it up in a hooks.json file inside your plugin:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/safety-guards.sh"
          }
        ]
      }
    ]
  }
}

The matcher is Bash, so this only runs for Bash commands. ${CLAUDE_PLUGIN_ROOT} resolves to your plugin's directory, so the path works on any machine.

The script reads the command from stdin as JSON, extracts it, and checks it against patterns. The skeleton is just the read, a fail-open guard, and one block rule:

#!/bin/bash
set -euo pipefail

# Claude Code passes the tool input as JSON on stdin
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"\s*:\s*"\([^"]*\)".*/\1/p' | head -1)

# Fail open: if we can't read a command, don't block
[ -z "$COMMAND" ] && exit 0

# BLOCK: rm -rf targeting home or root
if echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]*rf[a-zA-Z]*\s'; then
  if echo "$COMMAND" | grep -qE '(~[/\s]|\$HOME|/home/[^/\s]+[/\s]|\s+/\s+)'; then
    echo "BLOCKED: rm -rf targeting home or root directory." >&2
    exit 2
  fi
fi

# ... more block and warn rules go here

exit 0

The full script, with secret detection, the force-push gate and warnings, is at the end of this article.

Two design choices worth calling out.

Fail open. If the script can't parse a command, it exits 0 and lets it through. A safety hook that breaks every Bash call the moment its regex hits an edge case is worse than no hook, because you'll rip it out within a day. So block the clearly dangerous stuff and wave the rest through.

Block what's always destructive, warn on what's only sometimes wrong. rm -rf ~ is never what you want, so block it. git reset --hard is sometimes exactly the thing you need, so warn and let Claude decide with the warning sitting right there in context.

A real guard script grows more patterns over time. Common additions:

Block .env writes through the shell (echo ... > .env)
Block git push --force unless it's --force-with-lease
Warn on git clean -f, DROP TABLE, TRUNCATE, production keywords
Gate git push behind an explicit confirmation token

The whole thing is portable: a shell script and a JSON file, with no daemon and nothing to install. It rides along in your plugin and works on Linux, macOS, WSL and Git Bash on Windows. There's a tradeoff, of course. It only catches patterns you thought to write ahead of time - a smart filter, with all the holes any filter has.

A fuller version of this script, with the force-push gate and the full pattern list, lives in the reference repo: github.com/Nagell/claude-marketplace.

Approach B: Native sandbox - built-in filesystem and network isolation

Claude Code ships a sandbox you turn on with /sandbox. Instead of inspecting commands, it constrains what any command is allowed to do.

Two layers of isolation:

Filesystem - writes are locked to the current working directory by default. A command can read widely but can't write outside the project unless you allow it. You tune this with allowWrite and denyWrite rules.
Network - outbound traffic goes through a local proxy with an allowlist. Approved domains pass, everything else is blocked. No surprise calls to a random host.

The payoff is fewer interruptions. Because sandboxed commands can't escape the box, Claude Code stops asking you to approve them one by one. In practice that's a large cut in permission prompts during an autonomous session, which is the whole reason you'd run one.

Platform support is the catch:

macOS - uses the OS Seatbelt sandbox, works out of the box.
Linux / WSL2 - uses bubblewrap, which you install yourself (plus socat; Ubuntu 24.04+ needs an AppArmor tweak).
WSL1 - not supported.

Other caveats: Docker and watchman don't play well inside the sandbox, and there's an escape hatch. When a command fails because of sandbox restrictions, Claude can retry it with dangerouslyDisableSandbox. That retry runs outside the sandbox but goes back through the normal permission flow, so it still asks you. It's not a silent bypass. To remove the hatch entirely, set allowUnsandboxedCommands: false (Strict sandbox mode in the /sandbox panel) and the parameter is ignored.

Source: code.claude.com/docs/en/sandboxing

Approach C: Docker microVM - strongest isolation, team-friendly

When hooks and the native sandbox aren't enough, you go up a level: run Claude inside a Docker microVM.

This isn't a container sharing your host kernel. Each sandbox gets a full microVM with its own kernel and a private Docker daemon. Your dev environment is cloned in, Claude works inside it, and nothing it does touches the host. Worst case, you throw the VM away.

This is the right call for two situations:

Teams - everyone gets the same isolated environment, and a mistake in one is contained to one.
Long-running autonomous agents - if Claude is going to run for hours unattended, the blast radius of any single command should be a disposable VM, not your laptop.

The cost is setup and overhead. You're running a VM, which is heavier than a hook or the native sandbox. For a quick session it's overkill. But if you're leaving an agent running unattended overnight, it's the only one of the four that lets you actually sleep.

Official guide: Docker Sandboxes for Claude Code

Approach D: Community collections - standing on shoulders

You don't have to write every pattern yourself. Several maintained hook collections exist, and they've already hit the edge cases you haven't:

karanb192/claude-code-hooks - blocks the classics: rm -rf ~, fork bombs, curl | sh.
CodyLunders/claude-code-hooks-library - 55 hooks, 12 security-specific, including AWS credential scanning (AKIA[0-9A-Z]{16}) and an interactive installer.
disler/claude-code-hooks-mastery - educational, walks through multiple security patterns so you learn the mechanism, not just the config.
Boucle - a standalone safety hook framework for Claude Code: framework.boucle.sh.

There's also a DEV Community writeup of 10 hooks pulled from 108 hours of autonomous operation, which is exactly the kind of battle-tested list worth reading before you invent your own.

So skim one of these, lift the patterns that fit your setup, and drop them into your own guard script. You keep the portability of owning the file, and you skip relearning the lessons someone already paid for.

Comparison

	Custom hooks	Native sandbox	Docker microVM	Community hooks
Isolation level	Pattern-based filter	Filesystem + network	Full VM, own kernel	Pattern-based filter
Setup effort	Low (a script + JSON)	Low-medium (install on Linux)	High (VM tooling)	Low (install a collection)
Permission friction	Low	Very low (auto-allow)	Very low	Low
Portability	Excellent (just files)	OS-dependent	Needs Docker	Excellent
Platforms	Linux, macOS, Windows (Git Bash / WSL)	macOS and Linux native, Windows via WSL2 (no WSL1)	Anywhere Docker runs	Linux, macOS, Windows
Catches the unknown	No, only known patterns	Yes, by construction	Yes, by construction	No, only known patterns

The split that matters is the last row. A hook only catches what you already wrote a pattern for, whereas a sandbox constrains what any command can touch in the first place, so it stops the things you never saw coming too. That's why the strong setups stack them - a hook on top for fast, project-specific rules you can read at a glance, and a sandbox underneath as the backstop for everything else.

What to actually use

Most developers, most of the time: custom hooks. Lightweight, portable and you understand exactly what they do. Start here.
Frequent autonomous sessions: add the native sandbox on top. The interruption cut alone pays for the Linux setup.
Teams or overnight agents: Docker microVM. When the blast radius has to be zero, nothing else gets you there.

Start with the hook. Here's one to copy into a plugin's hooks/ directory and wire up through the hooks.json shown earlier:

#!/bin/bash
# safety-guards.sh - PreToolUse hook for Bash
# Exit 0 = allow, exit 2 = block (stderr shown to Claude)
set -euo pipefail

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"\s*:\s*"\([^"]*\)".*/\1/p' | head -1)
[ -z "$COMMAND" ] && exit 0

block() { echo "BLOCKED: $1" >&2; exit 2; }

# Destructive filesystem
echo "$COMMAND" | grep -qE 'rm\s+-[a-zA-Z]*rf[a-zA-Z]*\s' && \
  echo "$COMMAND" | grep -qE '(~[/\s]|\$HOME|/home/[^/\s]+[/\s]|\s+/\s+)' && \
  block "rm -rf targeting home or root"

# Hardcoded secrets
echo "$COMMAND" | grep -qE '(API_KEY|SECRET|TOKEN|PASSWORD)=['\''"]?[a-zA-Z0-9_\-]{16,}' && \
  block "possible hardcoded secret - use env vars"

# Unsafe force push
echo "$COMMAND" | grep -qE 'git\s+push\s+.*--force[^-]' && \
  ! echo "$COMMAND" | grep -qE 'force-with-lease' && \
  block "git push --force without --force-with-lease"

# Warn (allow)
WARNINGS=""
echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard' && WARNINGS="git reset --hard destroys uncommitted changes"
[ -n "$WARNINGS" ] && echo "{\"systemMessage\": \"SAFETY WARNING: $WARNINGS\"}"

exit 0

Ship it in your plugin and Claude Code runs it before every Bash call. (The file needs its executable bit, which you set once and commit; git preserves it, so nobody runs chmod after installing.) Add patterns as you find the ones that bite.

You can have Claude write these rules for you. If you do, ask it to test them too: have it feed the hook fake commands that should trip each pattern (a dummy rm -rf ~, a planted secret, a git push --force) and confirm they actually block. Ask it to check the regex isn't too loose while it's there, so a real command doesn't slip past. It's the fastest way to catch a pattern that's too greedy or too narrow before it catches you.

That's a safety net you own, in a file you can read in one sitting.

Get started

Use the starter template to get a clean slate with everything pre-wired: github.com/Nagell/claude-marketplace-template.

If you want to see a fuller working example with multiple plugins and real hook scripts, github.com/Nagell/claude-marketplace is the reference repo used throughout this series.

Build Your Own Claude Code Marketplace: Scaffold, Structure, and Auto-Updates

Dawid Nitka — Sun, 14 Jun 2026 16:52:08 +0000

TL;DR: A Claude Code marketplace is a GitHub repo with a specific folder structure. You create plugins inside it, push to GitHub, and anyone (including yourself) can install your plugins with two commands. This article shows you how to scaffold one from zero and add your first plugin. A one-command setup script comes later in the series, and auto-versioning plus release CI come pre-wired as a bonus in the starter template.

Every time I switched between my work machine and home setup, or got a new laptop, I'd lose an hour reinstalling the same Claude Code plugins and setting up the same tools. Wrong versions, configs I'd forgotten to copy over, the whole thing rebuilt from nothing. So I built a marketplace - a single GitHub repo that holds all my plugins and keeps them versioned.

Before we get into the structure: you can skip the scaffold entirely and use the starter template directly (link below). The rest of this article explains its structure.

Template: github.com/Nagell/claude-marketplace-template

You can pass this article URL directly to Claude Code and follow along.

What is a Claude Code marketplace?

A marketplace is a GitHub repository with a marketplace.json registry that Claude Code reads to discover plugins. Each plugin lives in its own subdirectory and has a plugin.json describing it.

There's no npm package and nothing to host, just a public repo.

Directory structure

your-marketplace/
├── .claude-plugin/
│   └── marketplace.json        ← the plugin registry
├── plugins/
│   └── your-plugin/
│       ├── .claude-plugin/
│       │   └── plugin.json     ← plugin metadata
│       ├── hooks/
│       │   ├── hooks.json      ← hook wiring (which hooks fire when)
│       │   └── your-guard.sh   ← the scripts hooks.json points to
│       ├── skills/             ← SKILL.md files (auto-loaded, or run with /name)
│       ├── agents/             ← agent definitions
│       └── .mcp.json           ← MCP server config
├── .github/
│   └── workflows/
│       └── release.yml
├── scripts/
│   └── generate-release-config.js
└── CLAUDE.md

A plugin can contain any combination of these. Start with what you actually use - you don't need all of them.

What can a plugin do?

Quite a bit more than you'd expect. A plugin can ship:

Skills - SKILL.md files that give Claude instructions for a domain. Claude loads one on its own when it's relevant, or you run it by name with /your-plugin:skill-name. A skill can be passive reference (a testing strategy, a code-review approach) or an action you trigger by hand.
Hooks - Scripts that run before or after Claude uses a tool. Common uses: blocking dangerous shell commands, auto-formatting files after edits, logging.
Agents - Named subagents with specific roles and tool access.
MCP servers - Registered via .mcp.json, giving Claude access to external tools and APIs.

A skill isn't limited to passive knowledge. It's Markdown that Claude executes, so a single one can install a package manager, configure your terminal, set up Nerd Fonts, pull files from a repo, walk a whole setup through and so on.

A note on CLAUDE.md inside a plugin

You'll notice the plugin folder structure doesn't include a CLAUDE.md. That's intentional.

A CLAUDE.md inside a plugin folder is not a recognized plugin component - Claude Code's plugin system ignores it. If you want a plugin to ship AI instructions, SKILL.md files in a skills/ directory are the correct mechanism. A plugin-level CLAUDE.md has no automatic effect.

That said, there's a useful pattern: a plugin can ship a skill that explicitly offers to copy an opinionated CLAUDE.md into the user's global ~/.claude/CLAUDE.md. The user opts in, the skill handles the copy, and the result is a consistent global configuration across machines. We'll cover exactly this in the article about one-command setup.

The marketplace.json

.claude-plugin/marketplace.json is the registry file Claude Code reads when someone adds your marketplace. Here's what it looks like when you're done:

{
  "name": "your-marketplace-name",
  "owner": { "name": "Your Name" },
  "version": "1.0.0",
  "description": "What your marketplace is for",
  "plugins": [
    {
      "name": "your-plugin",
      "source": "./plugins/your-plugin",
      "version": "0.1.0",
      "keywords": ["relevant", "tags"]
    }
  ]
}

You'll manage this file yourself as you add plugins - updating the list and bumping versions when things change. The starter template automates that for you: a CI script syncs this registry from your individual plugin.json files on every push, so you never have to touch it by hand, and auto-versioning from conventional commits rides along with it.

Creating your first plugin

A plugin needs exactly one file to exist: plugins/your-plugin-name/.claude-plugin/plugin.json.

{
  "name": "your-plugin",
  "version": "0.1.0",
  "description": "What this plugin does",
  "author": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "keywords": ["relevant", "tags"]
}

That's the minimum. Create the subdirectories for whatever components you're shipping (hooks, skills, agents) alongside it.

Publish on GitHub

Push the repo. It needs to be public - Claude Code fetches marketplaces directly from GitHub.

Install from your marketplace

Two commands inside Claude Code:

/plugin marketplace add your-username/your-marketplace-repo

This registers the marketplace with Claude Code. Replace your-username/your-marketplace-repo with your GitHub username and repo name.

/plugin install your-plugin-name@your-marketplace-name

This installs a specific plugin. The format is <plugin-name>@<marketplace-name> - the marketplace name comes from the name field in your marketplace.json.

Auto-versioning and CI

Bonus in the template: The starter template ships a GitHub Actions workflow and a sync script that drive version bumps from conventional commits (feat: → minor, fix: → patch) and keep marketplace.json in sync automatically. You don't build any of it - it's wired up and ready the moment you start from the template.

Under the hood it uses the Release Please GitHub Action and a small Node.js script. (The Action wraps the Release Please tool, which is where the docs live.) Conventional commits on main create a Release PR; merging it publishes a tagged GitHub Release.

Enable auto-updates

Once your marketplace is live, Claude Code can check for plugin updates automatically.

Via the UI: run /plugin → Marketplaces tab → select your marketplace → Enable "Auto-update". After an update, Claude will prompt you to run /reload-plugins. No full restart required.

Alternatively - edit settings.json directly (useful if you're setting this up by hand or passing it to an agent):

{
  "extraKnownMarketplaces": [
    {
      "url": "https://github.com/your-username/your-marketplace-repo",
      "autoUpdate": true
    }
  ]
}

Get started

Use the starter template to get a clean slate with everything pre-wired: github.com/Nagell/claude-marketplace-template.

If you want to see a fuller working example with multiple plugins and real hook scripts, github.com/Nagell/claude-marketplace is the reference repo used throughout this series.

Creating a scalable Monorepo for Vue - Nx

Dawid Nitka — Sun, 01 Jun 2025 13:00:02 +0000

As your codebase grows, so does the complexity of managing multiple apps and libraries. At this point Nx can help with its graph, but more importantly it can orchestrate all builds and tests in monorepo and keep you sane while managing dozens of packages.

In essence Nx is capable of running tasks in parallel based on what has changed from the previous commit. It also respects dependencies, ensuring that libraries needed by others are built first.

Key Features

Project Graph & Dependency Awareness
Nx automatically analyzes your workspace and builds a project graph, understanding how your apps and libraries depend on each other. This
allows you to build or test only what has changed and furthermore what is directly influenced by it, based on the changes between the current and the previous commit.
Code Generation
Nx provides some nice generators for scaffolding new apps, libraries,
etc. I found them to be decent for Vue, but if you like it your way you can of course just ignore them.
Advanced Caching
Nx caches build and test results, so repeated commands are lightning
fast. It can even share cache results across CI runs and between developers (Caution: sharing is a nice but paid feature - still very useful for enterprise clients).
Powerful CI/CD
Nx can run tasks in parallel, only for affected projects, and provides detailed output for CI pipelines.

How to Configure Nx in Your Monorepo

Install Nx

If you’re starting from scratch, you can create a new Nx workspace with:

pnpx create-nx-workspace

In an existing monorepo, install Nx as a dev dependency and run init:

pnpm add -D nx

nx init

Nx Workspace Structure

Nx expects some sub-directories with package.json or it's internal project.json file by default as a marker of a package. Sample structure can look like this:

/
├── apps/
│   └── app_1/
├── libs/
│   └── commons/
│   └── ui/
├── nx.json
├── workspace.json (or project.json or package.json files)
├── tsconfig.base.json
├── pnpm-workspace.yaml
└── package.json

apps/: Applications (SPA, SSR, etc.)
libs/: Reusable libraries (UI, utilities, etc.)
nx.json: Nx-specific configuration (project graph, tasks, etc.)
workspace.json: Project definitions (can be split into per-project project.json or package.json),
pnpm-workspace.yaml: Defines workspace packages for pnpm

Adding Nx Plugins

Nx supports plugins for frameworks and tools. For example, to add Vue support:

pnpm add -D @nx/vue

Or for Storybook:

pnpm add -D @nx/storybook

With the mentioned plugins you can run and utilize Nx commands for these frameworks, but also use them for scaffolding new projects.

To start with using commands as well as Nx packages I recommend the vscode plugin Nx Console. It’s a great tool for exploring available options and features.

Basic Nx Commands

Run a target:

  pnpm nx build:staging @monorepo/app_1
  pnpm nx lint @monorepo/commons

Run for affected (changed from the last commit) projects only:

  pnpm nx affected -t build:staging

Start the project graph:

  pnpm nx graph

List of installed and available plugins:

  pnpm nx list

graph

It helps you visualize the dependencies between your packages. If you want to categorize your packages correctly in this browser based tool, I recommend either generating workspace.json or a bunch of project.json files, or as in my case (the simplest one) just adding this to your package.json files:

{
    "name": "@monorepo/ui",
    "version": "1.0.0",
    // ...
    "nx": {
        "projectType": "library" // or "application"
    }
}

affected

Running locally the affected command will work with default settings only if creating branch and making some changes as it compares your branch to the main. But you can always explicitly compare the current state with a state from a couple of commits ago for test purposes.

# run lint for packages which changed 
# between the current state and the state from 5 commits ago
pnpm nx affected -t lint --base=HEAD~5 --head=HEAD

This is the result of running lint for all packages in my monorepo template.

Not very spectacular, I know, but imagine how much build time you can save with a big monorepo while running this command on your server and executing commands in parallel only for the changed parts!

This is the last article in this series. If you want to learn more about creation of monorepo with Vue, check out other tutorials. If you prefer starting with a solid foundation - try this template, where I’ve put all of this into practice.

Creating a scalable Monorepo for Vue - Shared configs

Dawid Nitka — Sat, 22 Feb 2025 12:20:09 +0000

Now that we have in place all needed packages (libs and apps) and established connections between them, we have to take care of required configs like vite.config.ts, .eslint.cjs and postcss.config.cjs. We could add all of them multiple times, but as we have monorepo let's use it to our advantage.

You can create a global configs directory in the root of monorepo and add all common configs there, like: vite.application.ts, vite.service.ts, etc.

Later you can import them into apps and libs in the config files and refine them with some overwrites. Of course the overwriting or rather merging step can be a bit problematic. Luckily there are already tested solutions out there like this nice merge function made by John Hildenbiddle.

Merge sample

export default merge

/**
 * Recursively merges the specified object instances
 * @param instances Instances to merge, from left to right
 */
function merge(...instances) {
    let i = instances.length - 1
    while (i > 0) {
        instances[i - 1] = mergeWith(instances[i - 1], instances[i])
        i--
    }
    return instances[0]
}

/**
 * Merge an instance with another one
 * @param target Object to merge the custom values into
 * @param source Object with custom values
 * @author inspired by [jhildenbiddle](https://stackoverflow.com/a/48218209).
 */
function mergeWith(target, source) {
    const isObject = obj => obj && typeof obj === 'object'

    if (isObject(target) && isObject(source)) {
        Object.keys(source).forEach((key) => {
            const targetValue = target[key]
            const sourceValue = source[key]

            if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {
                target[key] = targetValue.concat(sourceValue)
            }
            else if (isObject(targetValue) && isObject(sourceValue)) {
                target[key] = merge(Object.assign({}, targetValue), sourceValue)
            }
            else {
                target[key] = sourceValue
            }
        })
    }

    return target
}

With this you can add your vite.application.ts template:

import * as path from 'path'

import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({
    root: process.cwd(),

    server: {
        host: 'localhost',
        open: true,
    },

    preview: {
        host: 'localhost',
    },

    plugins: [ vue(), nxViteTsPaths() ],

    // Uncomment this if you are using workers.
    // worker: {
    //     plugins: () => [ nxViteTsPaths() ],
    // },

    resolve: {
        alias: {
            '@': path.resolve(process.cwd(), './src'),
        },
    },

    build: {
        reportCompressedSize: true,
        commonjsOptions: {
            transformMixedEsModules: true,
        },
    },
})

and the index.ts file collecting all the configs:

import merge from './merge'
import getProxyConfiguration from './proxyConfig'
import applicationConfiguration from './vite.application'

import type { UserConfig } from 'vite'

export { getProxyConfiguration }

/**
 * Returns Vite build configuration for client applications,
 * optionally amended with the specified options
 * @param options Custom build options
 * @returns Vite build configuration
 */
export function getApplicationConfiguration(options: UserConfig = {}) {
    return getConfiguration(applicationConfiguration, options)
}

/**
 * Returns Vite build configuration amended with the specified options
 * @param configuration Default build options
 * @param options Custom build options
 * @returns Vite build configuration
 */
function getConfiguration(configuration: UserConfig, options: UserConfig = {}) {
    const result = merge(
        // Default configuration
        configuration,
        // Custom options to override the default configuration
        options
    )

    // Handy when you need to peek into that final build configuration
    // console.warn(JSON.stringify(result, null, 2))

    return result
}

Finally the usage of the whole template can look like this:

// eslint-disable-next-line
import { getApplicationConfiguration, getProxyConfiguration } from './../../config/vite'

export default getApplicationConfiguration({
    cacheDir: '../../node_modules/.vite/apps/app_1',

    server: {
        port: 5005,
        proxy: {
            // sample proxy configuration
            '/api': getProxyConfiguration('https://localhost:7148/'),
        },
    },

    preview: {
        port: 5005,
    },

    build: {
        outDir: '../../dist/apps/app_1',
    },
})

Notice that instead of standard export default { … } we are using the getApplicationConfiguration(…). It allows us to use the predefined template and overwrite some specific parts.

Check out the implementation in the sample repo. Usage sample can be found in the app.

Eslint, postcss, etc

The same applies to other repeatable configs like eslint. No matter if you are using the old syntax (8.x.x) or the newer one using export default (9.x.x) - you can still add a bunch of custom configs like I did here to import them as needed in the apps and libs (sample)

Generally speaking, in monorepo you can make your life easier by reusing many common configs by sharing them. After a bit of initial cost, adding yet another app or lib will be much easier.

If you want to learn more about creation of monorepo with Vue, check out other tutorials in the series. If you prefer starting with a solid foundation - try this template, where I’ve put all of this into practice.

In the next one, we will talk about builds and parallelization with Nx.

Creating a scalable Monorepo for Vue - Libs vs Apps

Dawid Nitka — Sat, 25 Jan 2025 18:00:12 +0000

One of the steps in creating a monorepo is splitting apps and libraries. But how to take them apart? What is a library and do you have to publish it somewhere?

The simplest answer is that a library is reusable code. To name a few, it can be your UI library, API files that will be reused, or even some library with useful functions—our well-known: helperThis, helperThat, ... In the case of Vue, it can also include a bunch of compostables (ex. useSomething). There's no need to publish them anywhere. They will be used directly from your libraries.

Setting up the consumer (app)

Let's assume you already have a couple of candidates to put them outside your app and reuse them. The next question is how to connect them.

In the previous post I mentioned adding libraries to the package.json (sample below) file, but it's only one side of the story.

{
    "name": "@monorepo/app_1",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        // ...
    },
    "dependencies": {
        "@monorepo/commons": "workspace:*",
        "@monorepo/ui": "workspace:*"
    },
    // ...
}

Setting up the provider (library)

The other side which is the library has to define all files that should be approachable from outside. Of course, it can be just some index file, but it could be a sub-directory as well - there's no need to set every file independently. All this has to be put in the library's package.json file.

{
    "name": "@monorepo/commons",
    "version": "1.0.0",
    "type": "module",
    "exports": {
        ".": "./src/index.ts",
        "./composables/*": "./src/composables/*"
    },
    "scripts": {
        // ...
    },
    "dependencies": {}
}

Typescript and intellisense

The sample above should give you already an idea of how to connect things. To use it you can just:

import someHelper from "@monorepo/commons/composables/analytics"

You will still notice that TypeScript running in the background cannot recognize imported libraries. To solve this add explicit such paths to the project's tsconfig.json file (section paths).

{
    "compilerOptions": {
        "paths": {
            "@monorepo/commons": [
                "../../libs/commons/src/*"
            ],
        },
    },
    // ...
}

The first part is what you want to use during the import and the second is a direct path to the file or directory.

As a bonus it also makes Vue components show you all expected parameters in the form of intellisense as if they were added directly to your project.

Setting up custom paths

I explicitly set @monorepo/commons to point to the library's /src directory. If the /src directory is exported in the library's package.json, it's enough to make it work.

You can also define your own, so-to-say, "nicknames". This practice is often used to create paths that are shorter and thus easier to use and remember.

For example, instead of using:

import someHelper from "@monorepo/commons/composables/analytics"

you could use

import someHelper from "@monorepo/commons/analytics"

To achieve this, define such a shortcut in the library's package.json:

{
    "name": "@monorepo/commons",
    // ...
    "exports": {
        ".": "./src/index.ts",
        "./composables/*": "./src/composables/*",
        "./analytics/*": "./src/composables/analytics/*",
    },
}

and also add it to the app's tsconfig.json file:

{
    "compilerOptions": {
        "paths": {
            "@monorepo/commons": [
                "../../libs/commons/src/*"
            ],
            "@monorepo/commons/composables/*": [
                "../../libs/commons/src/composables/*"
            ],
            "@monorepo/commons/analytics": [
                "../../libs/commons/src/composables/analytics/*"
            ],
        },
    },
    // ...
}

Creating a scalable Monorepo for Vue - Workspaces

Dawid Nitka — Tue, 14 Jan 2025 21:56:28 +0000

In the previous post, I mentioned so-called workspaces. This is a good starting point which also will show how to structure your future and existing projects. The first one (starting without any projects) is easy, the second (existing ones) requires a bit more work but with a bit of luck, everything should run smoothly.

The below steps describe how to do this with pnpm. You could also use yarn berry or yarn classic. In such case this approach works slightly differently by adding such structure description to the package.json file. The rest is quite similar.

Wait, but why not npm? I've heard that it also has workspaces.

AFAIK it's still not monorepo-ready due to serious problems with hoisting and the lack of ability to solve such dependencies. A good explanation of the struggle with npm caveats is provided in this article ;)

If you want to know more about creating a monorepo check out other tutorials in the series. If you prefer testing things on your own - try this template, where I put all of this into work.

Let's get to the work

Install pnpm if you don't have it yet:

npm install --global pnpm
#or
npm install --global corepack@latest
corepack enable pnpm
corepack use pnpm@latest-10

or you can follow the other options from the pnpm installation guide.

Create a new directory with a package.json file structured as follows:

{
    "name": "your_company_or_so",
    "version": "1.0.0",
    "private": true,
    "dependencies": {
        // all repeating dependencies
    }
    // ...
}

Add a pnpm-workspace.yaml file in the root directory to define your workspace structure:
```
packages:
  - 'apps/*'
  - 'libs/*'
  - 'whatever_else/*'
```
Add a bunch of sub-directories like apps, libs, etc. as defined in your workspace file.
Put your projects into the mentioned directories and/or create new ones.
Cut out the repeating dependencies and devDependencies from your projects' package.json files in the sub-directories and place them in the root package.json file. These are now connected to all your projects - exceptions are possible (read below).
Delete all your node_modules in the sub-directories if you copied them.

As mentioned in the previous post, you can directly connect your libraries to the projects by modifying the app's package.json file like so (more on this in the next article):

{
    "name": "@monorepo/app_1",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        // ...
    },
    "dependencies": {
        "@monorepo/commons": "workspace:*",
        "@monorepo/ui": "workspace:*"
    },
    // ...
}

Go to the root directory and install dependencies for all the projects at once:
```
pnpm i
```

FAQ

What about the dependencies that are not identical?

First consider bringing them to the same version, preferably the newer ones.

It's too time-consuming right now.

I get it—deadlines, and so on. You can just leave them where they are. I would still strongly recommend having only one version of Vue, React, Typescript, etc., because the more packages tied to the same version, the easier it is to update all your projects at once and deal with refactors after updating all the projects in one go.

Fine, I updated what I could, but there are still some dependencies requiring different versions.

It's fine, there is nothing wrong with it. Decide which version is more common and move this one to the root package.json. The less common version will stay in the package.json file of the project that is using it. This way, you signal your package manager that you need that specific version in a particular project, and it will be installed independently.

What about dependencies that are used only once? Should I move them as well?

It's up to you. If you assume that they will be used more often, sure, move them. Are they used only once for this specific project, and it's highly unlikely that it will change? Nah, you don't have to move it and pollute the root package.json.

Adding new dependencies

If you need to add something new to your monorepo you have two options:

Install a package for the entire workspace - run it in the root directory

# for dependencies 
pnpm add <package-name> -w

# for devDependencies
pnpm add <package-name> -Dw

Install it only for one of the apps / libs - run it in the app / lib directory

# for dependencies
pnpm add <package-name>

# for devDependencies
pnpm add <package-name> -D

Troubleshooting

I have some problems with dependencies with different versions.

You can try omitting this one migration to the root package.json file and keeping it in the projects' package.json files instead.

Creating a scalable Monorepo for Vue - Intro

Dawid Nitka — Tue, 14 Jan 2025 21:29:45 +0000

Hello world,

which means that this is my first article — first of many — as I intend to write a series on creating a monorepo structure for Vue.

What problem are we trying to solve?

Vue has become quite popular over the years, and more mid-size companies — and even some big names like Nintendo, Adobe, or Gitlab to name a few — are adopting it. Sometimes, they even choose it as the primary Framework for their products. That's why growing codebases containing many Vue packages are becoming common.

Juggling with projects and packages, publishing, updating, and dealing with the consequences of postponing the last step longer than we intended, due to fast-paced workflows. Many of us were already there, or are right now. This raises the question:

Is there a good alternative and what are the trade-offs?

In this series, I'll try to deliver some answers, as well as provide one of the solutions which you can see complete in this template. Feel free to use it as a base to kickstart your project or simply try it out.

If you have any questions, feel free to leave a comment or add a suggestion in the sample repo.

Monorepo

There is at least one good option on which we will focus as it's definitely a mature and battle-proven one - monorepo.

In contrary to microservices, which have a bunch of additional complexity this one embraces strengths of a monolith structure. I recommend a very good article on that matter from Maxi Ferreira - May I Interest You In a Modular Monolith?

The simple explanation is that we put everything into one directory. That's it? Well... not exactly. There are many additional possibilities, but let's start with the easy stuff.

One repo, but not much more

In the simplest form, it means that we create one repository with a bunch of sub-directories for our projects and libraries (packages) and that's it. The rest stays as it is: pushing to the origin, publishing with npm or Lerna. Maybe even with semantic-release if you've already made some optimization of the process.

Pros:

Many projects in one place -> less opened windows
Better overview of your team's work

Cons:

More branches -> potential chaos in the git tree

Add workspace

But what about managing external dependencies and consuming your libraries (packages)?

If you don't want to go to every project and update dependencies manually you should consider so-called workspaces. More about them in the next article in the series. In short, they will allow you to update more, maybe even all dependencies at once, and still keep full control over your projects, when some more granular interference will be required.

Sample workspace configuration with pnpm

To enable workspace features in pnpm, you need a pnpm-workspace.yaml file at the root of your repository.

packages:
  - 'apps/*'
  - 'libs/*'

This file will tell pnpm to treat all projects in the apps and libs directories as workspace packages.

More about it in the pnpm workspace docs.

With pnpm, you can manage workspaces and dependencies across all your projects in monorepo.
A couple of basic commands:

# Add a dependency to all projects in the workspace
pnpm add <package-name> -w

# Add a devDependency to all projects in the workspace
pnpm add <package-name> -Dw

# Add a dependency to a specific project
cd apps/app_1
pnpm add <package-name>

# Add a devDependency to a specific project
cd apps/app_1
pnpm add <package-name> -D

# Update all dependencies in the workspace to their latest versions
pnpm update --latest

Pros:

Faster update of dependencies for many projects at once
Less juggling with versions

Cons:

Requires updating more projects at once if they are tied to the same dependency in the root directory. They can still be split but it's somehow contrary to the goal

Add direct connection of dependencies

The workspaces are allowing us to manage external and internal dependencies way more easily. But what if I told you that you can directly use your other projects without even building them, not even mentioning publishing? With correct typescript configuration, you can even have types and intellisense still working. That is what you can achieve by connecting other of your libraries (previously packages) in your package.json like this:

{
    "name": "@monorepo/app_1",
    "version": "1.0.0",
    "type": "module",
    "scripts": {
        // ...
    },
    "dependencies": {
        "@monorepo/commons": "workspace:*",
        "@monorepo/ui": "workspace:*"
    },
    // ...
}

Notice the asterisks instead of version numbers. These mean that we are using whatever version is the newest. In our case, it's always the local one.

Pros:

Always the current version (also while developing in branches)
No need to publish libraries as packages and reinstall them
No local linking required to try out new library versions

Cons:

After a merge, dependencies might differ, potentially causing problems

This caveat can be mitigated with good test coverage and TypeScript running automatically through the complete codebase on the server before every build (which I highly recommend, regardless; ex. on the dev branch). This can be easily automated with husky.