Before you start: Claude Code, Bun and git

Before you start

A Claude Code mod is a small plugin of TypeScript functions that runs inside Claude Code itself: it can draw a line above the prompt, open a side pane, hold a tool call until you answer, or watch every command go by. In this workshop you build four of them, the four we run every day, and you finish with a gate that refuses to install a mod that would fail open.

Everything here was built and tested on Claude Code 2.1.291 to 2.1.294, on Linux. The macOS and Windows commands are the official installers; we did not run them ourselves. The times are estimates.

What you need

Get it on your machine

Claude Code:

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.sh | bash

Bun:

curl -fsSL https://bun.sh/install | bash

powershell -c "irm bun.sh/install.ps1 | iex"

curl -fsSL https://bun.sh/install | bash

git:

xcode-select --install

winget install --id Git.Git -e

sudo apt install -y git

On Fedora, use sudo dnf install -y git instead of apt.

Check all three. Each prints a version; Claude Code must say 2.1.291 or higher:

claude --version
bun --version
git --version

Then make the folder every step works in:

mkdir -p ~/claude-mods && cd ~/claude-mods && git init

Known gotchas

These are the ones we hit while building the mods; none is invented.

• The mods API is early access. The engine says so in its own type file: the surface may change between releases. When a step’s code stops validating after an update, read the new types (step 2 shows where) before you change anything else.
• The Desktop Code tab takes no command-line flags. Where a step says claude --plugin-dir <folder>, the Desktop app needs the folder in the CLAUDE_CODE_PLUGIN_DIRS variable of your settings’ env block instead.
• A mod’s slash command does not run under claude -p "/name". In a headless run the text goes to the model as a plain prompt. Test commands in an interactive session.
• An edit to an installed mod needs /reload-plugins. Nothing reinstalls; the folder is read in place.
• In a Bun workspace, never run bunx tsc. In our monorepo it replaced node_modules and broke the install. Step 7 runs a pinned tsc instead.