Building and publishing a Claude Code mod
A mod is a Claude Code plugin with a hooks module: a .js or .ts file
that Claude Code loads into its own process. Claude Code calls your functions
on events (a tool call, a submitted prompt, a part of the interface being
drawn). Each function can observe the event, rewrite it, or answer it. Mods
shipped in Claude Code v2.1.287. This skill was verified on v2.1.300.
Official manual: https://code.claude.com/docs/en/plugins/mods/overview.
The built-in plugin-authoring skill (/plugin-authoring) gives Claude the
events and methods of your exact build. Use it together with this skill.
When to use
- Triggers: 'make a mod', 'Claude Code mod', 'add a pane to Claude Code',
'change the spinner', 'hooks module', 'register.js', 'claude plugin
validate', 'claude plugin test', 'publish a mod', 'mod does nothing'.
- You want something a settings hook, skill, or MCP server cannot do: draw
an interface, redraw Claude Code's own rows, hold a tool call while you
ask the user, or run a
/command with no model turn.
- Siblings:
git-guardrails-claude-code (settings-hook guards),
claude-code-context-diet (trim what each request carries),
agentic-cli-npm-package (CLI + MCP companions), vscode-extension.
Pick the right tool first
| You want |
Use |
| A pane, a band above the prompt, a toast, a changed spinner or tool row |
Mod |
A /command that runs your code at once, even while Claude works |
Mod |
| To hold a tool call, ask the user, then allow or deny |
Mod ($.ui.ask) |
| To block, allow or log an event with a script you already have |
Settings hook |
| Instructions you keep pasting into chat |
Skill |
| Claude must reach an external system |
MCP server |
One plugin can hold a mod, skills, and an MCP server together.
The layout
my-mod/
├── .claude-plugin/
│ └── plugin.json # manifest; mods add no required fields
├── hooks/
│ ├── hooks.json # { "modules": ["./register.js"] } <- this key makes it a mod
│ └── register.js # the hooks module; exports register(on, options)
└── tests/
└── my-mod.test.ts # run by `claude plugin test`
No Node.js, bundler, or build step is needed. Claude Code loads .js, .mjs,
.cjs, .jsx, .ts, .mts, .cts, and .tsx directly, as ES modules.
A working sample with tests is in example/tool-tally/.
It counts tool calls beside the spinner, adds /tally, and refuses force
pushes with a guard that fails closed.
The hook shape
let calls = 0 // module state, shared by all hooks
export function register(on) {
on('tool.call', async ($, e, next) => { // $ = mods API, e = frozen event
calls += 1
$.ui.invalidate('ui.render') // ask for a redraw
return next(e) // observe: pass on unchanged
})
on('ui.render', { component: 'Spinner' }, async ($, e, next) =>
next({ ...e, props: { ...e.props, suffix: ' · ' + calls }})) // rewrite: pass a copy
on('tool.call', { tool: 'Bash' }, async ($, e, next) =>
/rm -rf \//.test(e.command) ? { deny: 'Refused.' } : next(e)) // answer: no next()
}
- Observe: do work,
return next(e). To act after, const r = await next(e).
- Rewrite:
next({ ...e, field }). e is deeply frozen. Assignment throws.
- Answer: return a result and skip
next. Later mods and Claude Code do not run.
- Matcher: the second argument to
on. A field takes a value, an array,
or a regex: { tool: ['Edit', 'Write'] }, { tool: /^mcp__github__/ }.
'*' matches every event except telemetry. 'classic.*' matches every
settings-hook event (classic.Stop, classic.PostToolUse, ...).
Events you use most
| Event |
Fires when |
Return |
session.start |
Before the first prompt, and after each reload of the mod |
next(e) |
tool.call |
A tool is about to run |
next(e), { deny }, or { result } |
tool.check |
The allow/ask/deny decision; next(e) gives what rules decided |
{ decision, reason } |
prompt.submit |
A prompt is sent |
next({...e, text}), next({...e, context}), { drop } |
command.run |
A /command runs |
{ text }, {}, or next(e) |
turn.step |
One model request (async generator) |
yield* next(e), next({...e, model}) |
turn.complete |
A turn ends |
next(e), or { text } for a line under the answer |
ui.render |
A render site is drawn |
an element tree, or next(e) |
ui.press / ui.input / ui.select |
A control you drew is used |
|
classic.SessionStart |
After /clear, /resume, /branch too |
next(e) |
Render sites for ui.render: Pane, AbovePrompt (the band), Spinner,
UserMessage, AssistantMessage, ToolUse, ToolResult, ToolGroup,
CommandOutput, AskUserQuestion, ToolProgress, TurnDuration,
InfoNotice, SessionMode, PromptHint. Elements come from
$.ui.resolve(e): Box, Text, Button, Link, Code, Markdown,
Input, Select, plus Svg (Desktop and VS Code only), Raster and Image
(terminal only), and Client.
Mods API you use most
| Call |
Does |
$.command.register({ name, description }) |
Adds a /command. Answer it in a command.run hook. |
$.ui.open({ id, title, focus: true }) |
Opens a pane. Draw it in ui.render with e.requestId === id. |
$.ui.toast(text) / $.ui.log(text) |
Toast at top right / dim transcript line Claude does not read |
$.ui.log(text, { to: 'debug' }) |
Line in the debug log only |
$.ui.ask(question, [labels]) |
Holds the hook until the user picks. Rejects in -p. |
$.state + atom, read, update from claude-code |
Reactive state that survives a hot reload |
$.store.get/set |
JSON key-value store shared by every session on the machine (4 MiB) |
$.process.run([...argv]) |
Runs a program (30 s default timeout) |
$.http.fetch, $.fs.read/write, $.model.complete |
Network, files (4 MiB), a model call on the user's plan |
$.session.usage() |
Context tokens, window, percent, rate limits, cost |
The full reference is the .d.ts that Claude Code writes into
.claude-plugin/types/ when it loads your mod from --plugin-dir. Trust it
over any page, this one included.
Make one
Ask Claude
In an interactive session, describe the mod: make a mod that shows the current git branch above the prompt. Claude writes it under
~/.claude/dev-mods/<session-id>/<name>/. Approve Enable for this
session at the hot-reload question. The mod reloads at the end of each turn
that changes it.
That folder is deleted after cleanupPeriodDays. To keep the mod, copy it to
a directory of your own, such as ~/mods/git-branch.
Write it yourself
- Create the three files from The layout.
- Start a session on the working copy:
claude --plugin-dir ./my-mod.
- Edit and save. The transcript prints a reload line with the hook list.
- Validate:
claude plugin validate --strict ./my-mod.
- Test:
cd my-mod && claude plugin test.
- Run end to end with no model turn:
claude -p "/tally" --plugin-dir ./my-mod.
To change an existing mod with Claude, start with --plugin-dir pointed at it.
Claude's edits then load in the same session.
Validate and test
claude plugin validate runs the same static analysis Claude Code runs at
load. Read its lines:
❯ ./register.js hooks: session.start, tool.call, tool.call{tool=Bash}, command.run{command=tally}, ui.render{component=Spinner}
❯ ./register.js answers its own command: command.run{command=tally}
❯ ./register.js gating hook without .catch: tool.call
❯ ./register.js gating hook with .catch: tool.call{tool=Bash}
❯ ./register.js calls: $.command.register, $.ui.invalidate
✔ Validation passed
If an event you meant to handle is missing from hooks:, Claude Code will not
call that hook either. calls: is what a reviewer reads to decide whether to
trust the mod.
claude plugin test runs every *.test.ts with no session, sign-in, or
network. The test's $ acts as Claude Code. Its on registers stubs that
answer in Claude Code's place:
import { expect, test } from 'claude-code/testing'
test('a force push is refused', async ($, on) => {
on('tool.call', () => ({ result: 'pushed' })) // stub the real tool
const out = await $.tool.call({ tool: 'Bash', command: 'git push -f origin main' })
expect(out.deny).toMatch(/Force pushes are refused/)
})
- A stub for a mods API call returns
{ value }: on('store.get', () => ({ value: 7 })).
- A stub for a Claude Code event returns the event's result:
{ result: 'ok' }.
- Kit mocks:
mock.clock(on), mock.store(on, {...}), mock.env(on, {...}), mock.session(on).
- Draw a site with
$.ui.mount({...}), then press, input, select, find.
- The command exits 1 on failure, so it works in CI.
example/verify.sh runs validate, the tests, and the
headless /tally check in one go.
Publish
A mod publishes exactly as a plugin does.
- Name it for good. Kebab-case, and never starting with
claude-,
anthropic-, or cc-plugin-. Validation refuses those names. A rename
breaks every install, so set displayName for the label instead.
- Version it. Bump
version on every release, or omit it in a
git-hosted marketplace so the commit SHA is the version. If you set it and
forget to bump it, claude plugin update says the user is already current.
- Fill the metadata.
description, author, homepage, repository,
and a README.md that states the Claude Code version you tested with.
Events and methods change between releases.
- Validate strictly:
claude plugin validate --strict ./my-mod.
- Pick a route:
| Audience |
Route |
| A few people |
Send the folder or a .zip. They run claude --plugin-dir ./my-mod, or --plugin-url <zip URL>. |
| Your team, or anyone |
Add .claude-plugin/marketplace.json to a git repo (below). |
| Your organization |
An admin installs it through managed settings (prependPlugins / appendPlugins). |
| claude.ai, Cowork, and Claude Code users |
Submit at https://claude.ai/directory/manage (paid plan). Users get it as <name>@synced. |
A marketplace in the plugin's own repo:
{
"name": "your-marketplace",
"owner": { "name": "Your Name" },
"plugins": [{ "name": "my-mod", "source": "./" }]
}
Users install it with:
claude plugin marketplace add your-org/your-repo
claude plugin install my-mod@your-marketplace
# or in a session: /plugin install my-mod --marketplace your-org/your-repo
After an install from the shell, run /reload-plugins in an open session.
Check what loaded with /plugin: a dim line reads 1 mod active · my-mod.
Pitfalls
Each of these makes a mod fail or do nothing. Items marked seen were
reproduced on v2.1.300 while building example/tool-tally.
Validation failures
- seen
const ui = $.ui fails: $.ui is used as a value. Write every
call in full: $.ui.toast(...). Do not destructure, alias, or index $.
You can pass $ to a top-level function in the same file.
- seen A typo in an event name fails:
"tool.calls" is not an event.
- seen Two
on('session.start', ...) without a matcher fail:
registered twice without a matcher. Put all start-up work in one hook.
- seen
"module" instead of "modules" in hooks.json fails with
must have hooks ... or modules.
- seen A plugin named
claude-tally fails: names that pass as
Anthropic's own are reserved.
- The event name must be a string literal. A loop over names fails.
- Do not shadow
on inside register. Do not use dynamic import().
- Import only relative files inside the plugin, plus
claude-code.
- Hold each
atom(...) result in a const, not a let.
Passes validation, still breaks
- seen
require('fs') passes validate and then fails at load:
hooks module did not load: ReferenceError: require is not defined. Always
run claude plugin test as well. validate reads the code; it does not run it.
- A guard with no
.catch fails open. If it throws or times out before
next, Claude Code skips it and the tool runs. validate flags this as
gating hook without .catch. Add a .catch that returns { deny } when
next.called is false.
- A hook has 10 seconds of its own time (50 ms for
prompt.edit). Time spent
in a mods API call does not count. Time awaiting your own promise does. A
timed-out guard is skipped, so the held command runs.
- A blocking loop crashes the shared hooks worker. Claude Code unloads the
mod. Three crashes it cannot trace unload every installed mod.
State
- Module variables reset on every hot reload. Use
$.state or $.store.
/clear, /resume, and /branch reset $.state and do not fire
session.start again. Reload saved values in a classic.SessionStart
hook filtered on { source: ['clear', 'resume', 'fork'] }.
$.store get-then-set races between sessions. $.fs.write is not atomic.
Interface
- A pane your mod opens by itself (timer,
turn.start) appears only in a
terminal 144 columns wide, 110 after the user has opened it once. Open it
from a command or button, or check isPlaced in the result of $.ui.open.
focus, closeOnEscape, and holdToasts accept only true. Passing
false throws. Omit the field instead.
borderStyle: 'rounded' draws nothing. The valid name is 'round'.
- An invalid tree is replaced by Claude Code's own drawing, with a
ui.render (Pane) refused: line. Check e.surface before using
terminal-only or Desktop-only elements.
claude -p and the Agent SDK run hooks but draw nothing. Fall back to a
transcript line or a command's text reply.
- Redraws are throttled to 10 a second (30 for the visible pane). Do not call
invalidate in a tight loop.
Development loop
- Editing an installed copy does nothing. Claude Code runs a cached copy
per version. Develop against
--plugin-dir.
- Errors in an installed mod appear only in the debug log. Start with
claude --debug-file ./mod.log, then tail -f ./mod.log | grep my-mod.
- A save that breaks the module keeps the last working version running, with
reload failed, the previous version stays loaded.
- A mod Claude writes does not load in
claude -p, dontAsk mode, an
untrusted folder, --safe-mode, --bare, or with disableAllHooks.
- If the hot-reload question times out three times, it stops asking. Copy the
mod out and use
--plugin-dir.
- Remove any
CLAUDE_CODE_ENABLE_FUNCTION_HOOKS left from early access. It is
ignored now.
- In auto mode, a hook that changes a tool call's input after the classifier
reviewed it gets the call denied. Rewrite inputs only when you must.
Security
A mod is not sandboxed. It runs as you: it reads files and secrets, sees every
prompt and tool call, can approve a call before you are asked, and can spend
your usage. It cannot restyle the permission prompt. Before you install
someone else's mod, clone it and read the hooks: and calls: lines from
claude plugin validate ./their-mod. Look hard at $.process, $.http,
$.fs.write, and tool.check.
Ideas worth building
From Ivo Kund's first look
(https://www.ivokund.com/first-look-at-claude-code-mods-spoiler-yes-use-one-now/)
and Anthropic's samples:
1---2name: claude-code-mods3description: "Use when building, testing, debugging or publishing a Claude Code mod: a plugin whose JavaScript or TypeScript hooks module runs inside Claude Code to draw panes, restyle the spinner or tool rows, guard tool calls, rewrite prompts, or add /commands that run with no Claude turn. Covers mod vs settings hook vs skill vs MCP, the three-file layout, the static-analysis rules that fail validation, the --plugin-dir hot-reload loop, claude plugin validate and claude plugin test, publishing through a marketplace or Anthropic's directory, and the pitfalls that make a mod silently do nothing."4metadata:5 source: https://skillmd.com/skills/pooriaarab/claude-code-mods6---78# Building and publishing a Claude Code mod910A mod is a Claude Code plugin with a **hooks module**: a `.js` or `.ts` file11that Claude Code loads into its own process. Claude Code calls your functions12on events (a tool call, a submitted prompt, a part of the interface being13drawn). Each function can observe the event, rewrite it, or answer it. Mods14shipped in Claude Code v2.1.287. This skill was verified on v2.1.300.1516Official manual: <https://code.claude.com/docs/en/plugins/mods/overview>.17The built-in `plugin-authoring` skill (`/plugin-authoring`) gives Claude the18events and methods of your exact build. Use it together with this skill.1920## When to use2122- **Triggers:** 'make a mod', 'Claude Code mod', 'add a pane to Claude Code',23 'change the spinner', 'hooks module', 'register.js', 'claude plugin24 validate', 'claude plugin test', 'publish a mod', 'mod does nothing'.25- You want something a settings hook, skill, or MCP server cannot do: draw26 an interface, redraw Claude Code's own rows, hold a tool call while you27 ask the user, or run a `/command` with no model turn.28- Siblings: `git-guardrails-claude-code` (settings-hook guards),29 `claude-code-context-diet` (trim what each request carries),30 `agentic-cli-npm-package` (CLI + MCP companions), `vscode-extension`.3132## Pick the right tool first3334| You want | Use |35|---|---|36| A pane, a band above the prompt, a toast, a changed spinner or tool row | Mod |37| A `/command` that runs your code at once, even while Claude works | Mod |38| To hold a tool call, ask the user, then allow or deny | Mod (`$.ui.ask`) |39| To block, allow or log an event with a script you already have | Settings hook |40| Instructions you keep pasting into chat | Skill |41| Claude must reach an external system | MCP server |4243One plugin can hold a mod, skills, and an MCP server together.4445## The layout4647```text48my-mod/49├── .claude-plugin/50│ └── plugin.json # manifest; mods add no required fields51├── hooks/52│ ├── hooks.json # { "modules": ["./register.js"] } <- this key makes it a mod53│ └── register.js # the hooks module; exports register(on, options)54└── tests/55 └── my-mod.test.ts # run by `claude plugin test`56```5758No Node.js, bundler, or build step is needed. Claude Code loads `.js`, `.mjs`,59`.cjs`, `.jsx`, `.ts`, `.mts`, `.cts`, and `.tsx` directly, as ES modules.6061A working sample with tests is in [`example/tool-tally/`](example/tool-tally/).62It counts tool calls beside the spinner, adds `/tally`, and refuses force63pushes with a guard that fails closed.6465## The hook shape6667```javascript68let calls = 0 // module state, shared by all hooks6970export function register(on) {71 on('tool.call', async ($, e, next) => { // $ = mods API, e = frozen event72 calls += 173 $.ui.invalidate('ui.render') // ask for a redraw74 return next(e) // observe: pass on unchanged75 })7677 on('ui.render', { component: 'Spinner' }, async ($, e, next) =>78 next({ ...e, props: { ...e.props, suffix: ' · ' + calls }})) // rewrite: pass a copy7980 on('tool.call', { tool: 'Bash' }, async ($, e, next) =>81 /rm -rf \//.test(e.command) ? { deny: 'Refused.' } : next(e)) // answer: no next()82}83```8485- **Observe**: do work, `return next(e)`. To act after, `const r = await next(e)`.86- **Rewrite**: `next({ ...e, field })`. `e` is deeply frozen. Assignment throws.87- **Answer**: return a result and skip `next`. Later mods and Claude Code do not run.88- **Matcher**: the second argument to `on`. A field takes a value, an array,89 or a regex: `{ tool: ['Edit', 'Write'] }`, `{ tool: /^mcp__github__/ }`.90- `'*'` matches every event except telemetry. `'classic.*'` matches every91 settings-hook event (`classic.Stop`, `classic.PostToolUse`, ...).9293## Events you use most9495| Event | Fires when | Return |96|---|---|---|97| `session.start` | Before the first prompt, and after each reload of the mod | `next(e)` |98| `tool.call` | A tool is about to run | `next(e)`, `{ deny }`, or `{ result }` |99| `tool.check` | The allow/ask/deny decision; `next(e)` gives what rules decided | `{ decision, reason }` |100| `prompt.submit` | A prompt is sent | `next({...e, text})`, `next({...e, context})`, `{ drop }` |101| `command.run` | A `/command` runs | `{ text }`, `{}`, or `next(e)` |102| `turn.step` | One model request (async generator) | `yield* next(e)`, `next({...e, model})` |103| `turn.complete` | A turn ends | `next(e)`, or `{ text }` for a line under the answer |104| `ui.render` | A render site is drawn | an element tree, or `next(e)` |105| `ui.press` / `ui.input` / `ui.select` | A control you drew is used | |106| `classic.SessionStart` | After `/clear`, `/resume`, `/branch` too | `next(e)` |107108Render sites for `ui.render`: `Pane`, `AbovePrompt` (the band), `Spinner`,109`UserMessage`, `AssistantMessage`, `ToolUse`, `ToolResult`, `ToolGroup`,110`CommandOutput`, `AskUserQuestion`, `ToolProgress`, `TurnDuration`,111`InfoNotice`, `SessionMode`, `PromptHint`. Elements come from112`$.ui.resolve(e)`: `Box`, `Text`, `Button`, `Link`, `Code`, `Markdown`,113`Input`, `Select`, plus `Svg` (Desktop and VS Code only), `Raster` and `Image`114(terminal only), and `Client`.115116## Mods API you use most117118| Call | Does |119|---|---|120| `$.command.register({ name, description })` | Adds a `/command`. Answer it in a `command.run` hook. |121| `$.ui.open({ id, title, focus: true })` | Opens a pane. Draw it in `ui.render` with `e.requestId === id`. |122| `$.ui.toast(text)` / `$.ui.log(text)` | Toast at top right / dim transcript line Claude does not read |123| `$.ui.log(text, { to: 'debug' })` | Line in the debug log only |124| `$.ui.ask(question, [labels])` | Holds the hook until the user picks. Rejects in `-p`. |125| `$.state` + `atom`, `read`, `update` from `claude-code` | Reactive state that survives a hot reload |126| `$.store.get/set` | JSON key-value store shared by every session on the machine (4 MiB) |127| `$.process.run([...argv])` | Runs a program (30 s default timeout) |128| `$.http.fetch`, `$.fs.read/write`, `$.model.complete` | Network, files (4 MiB), a model call on the user's plan |129| `$.session.usage()` | Context tokens, window, percent, rate limits, cost |130131The full reference is the `.d.ts` that Claude Code writes into132`.claude-plugin/types/` when it loads your mod from `--plugin-dir`. Trust it133over any page, this one included.134135## Make one136137### Ask Claude138139In an interactive session, describe the mod: `make a mod that shows the140current git branch above the prompt`. Claude writes it under141`~/.claude/dev-mods/<session-id>/<name>/`. Approve **Enable for this142session** at the hot-reload question. The mod reloads at the end of each turn143that changes it.144145That folder is deleted after `cleanupPeriodDays`. To keep the mod, copy it to146a directory of your own, such as `~/mods/git-branch`.147148### Write it yourself1491501. Create the three files from [The layout](#the-layout).1512. Start a session on the working copy: `claude --plugin-dir ./my-mod`.1523. Edit and save. The transcript prints a reload line with the hook list.1534. Validate: `claude plugin validate --strict ./my-mod`.1545. Test: `cd my-mod && claude plugin test`.1556. Run end to end with no model turn: `claude -p "/tally" --plugin-dir ./my-mod`.156157To change an existing mod with Claude, start with `--plugin-dir` pointed at it.158Claude's edits then load in the same session.159160## Validate and test161162`claude plugin validate` runs the same static analysis Claude Code runs at163load. Read its lines:164165```text166 ❯ ./register.js hooks: session.start, tool.call, tool.call{tool=Bash}, command.run{command=tally}, ui.render{component=Spinner}167 ❯ ./register.js answers its own command: command.run{command=tally}168 ❯ ./register.js gating hook without .catch: tool.call169 ❯ ./register.js gating hook with .catch: tool.call{tool=Bash}170 ❯ ./register.js calls: $.command.register, $.ui.invalidate171✔ Validation passed172```173174If an event you meant to handle is missing from `hooks:`, Claude Code will not175call that hook either. `calls:` is what a reviewer reads to decide whether to176trust the mod.177178`claude plugin test` runs every `*.test.ts` with no session, sign-in, or179network. The test's `$` acts as Claude Code. Its `on` registers stubs that180answer in Claude Code's place:181182```typescript183import { expect, test } from 'claude-code/testing'184185test('a force push is refused', async ($, on) => {186 on('tool.call', () => ({ result: 'pushed' })) // stub the real tool187 const out = await $.tool.call({ tool: 'Bash', command: 'git push -f origin main' })188 expect(out.deny).toMatch(/Force pushes are refused/)189})190```191192- A stub for a mods API call returns `{ value }`: `on('store.get', () => ({ value: 7 }))`.193- A stub for a Claude Code event returns the event's result: `{ result: 'ok' }`.194- Kit mocks: `mock.clock(on)`, `mock.store(on, {...})`, `mock.env(on, {...})`, `mock.session(on)`.195- Draw a site with `$.ui.mount({...})`, then `press`, `input`, `select`, `find`.196- The command exits 1 on failure, so it works in CI.197198[`example/verify.sh`](example/verify.sh) runs validate, the tests, and the199headless `/tally` check in one go.200201## Publish202203A mod publishes exactly as a plugin does.2042051. **Name it for good.** Kebab-case, and never starting with `claude-`,206 `anthropic-`, or `cc-plugin-`. Validation refuses those names. A rename207 breaks every install, so set `displayName` for the label instead.2082. **Version it.** Bump `version` on every release, or omit it in a209 git-hosted marketplace so the commit SHA is the version. If you set it and210 forget to bump it, `claude plugin update` says the user is already current.2113. **Fill the metadata.** `description`, `author`, `homepage`, `repository`,212 and a `README.md` that states the Claude Code version you tested with.213 Events and methods change between releases.2144. **Validate strictly:** `claude plugin validate --strict ./my-mod`.2155. **Pick a route:**216217| Audience | Route |218|---|---|219| A few people | Send the folder or a `.zip`. They run `claude --plugin-dir ./my-mod`, or `--plugin-url <zip URL>`. |220| Your team, or anyone | Add `.claude-plugin/marketplace.json` to a git repo (below). |221| Your organization | An admin installs it through managed settings (`prependPlugins` / `appendPlugins`). |222| claude.ai, Cowork, and Claude Code users | Submit at <https://claude.ai/directory/manage> (paid plan). Users get it as `<name>@synced`. |223224A marketplace in the plugin's own repo:225226```json227{228 "name": "your-marketplace",229 "owner": { "name": "Your Name" },230 "plugins": [{ "name": "my-mod", "source": "./" }]231}232```233234Users install it with:235236```bash237claude plugin marketplace add your-org/your-repo238claude plugin install my-mod@your-marketplace239# or in a session: /plugin install my-mod --marketplace your-org/your-repo240```241242After an install from the shell, run `/reload-plugins` in an open session.243Check what loaded with `/plugin`: a dim line reads `1 mod active · my-mod`.244245## Pitfalls246247Each of these makes a mod fail or do nothing. Items marked **seen** were248reproduced on v2.1.300 while building `example/tool-tally`.249250### Validation failures251252- **seen** `const ui = $.ui` fails: `$.ui is used as a value`. Write every253 call in full: `$.ui.toast(...)`. Do not destructure, alias, or index `$`.254 You can pass `$` to a top-level function in the same file.255- **seen** A typo in an event name fails: `"tool.calls" is not an event`.256- **seen** Two `on('session.start', ...)` without a matcher fail:257 `registered twice without a matcher`. Put all start-up work in one hook.258- **seen** `"module"` instead of `"modules"` in `hooks.json` fails with259 `must have hooks ... or modules`.260- **seen** A plugin named `claude-tally` fails: names that pass as261 Anthropic's own are reserved.262- The event name must be a string literal. A loop over names fails.263- Do not shadow `on` inside `register`. Do not use dynamic `import()`.264- Import only relative files inside the plugin, plus `claude-code`.265- Hold each `atom(...)` result in a `const`, not a `let`.266267### Passes validation, still breaks268269- **seen** `require('fs')` passes `validate` and then fails at load:270 `hooks module did not load: ReferenceError: require is not defined`. Always271 run `claude plugin test` as well. `validate` reads the code; it does not run it.272- A guard with no `.catch` **fails open**. If it throws or times out before273 `next`, Claude Code skips it and the tool runs. `validate` flags this as274 `gating hook without .catch`. Add a `.catch` that returns `{ deny }` when275 `next.called` is false.276- A hook has 10 seconds of its own time (50 ms for `prompt.edit`). Time spent277 in a mods API call does not count. Time awaiting your own promise does. A278 timed-out guard is skipped, so the held command runs.279- A blocking loop crashes the shared hooks worker. Claude Code unloads the280 mod. Three crashes it cannot trace unload every installed mod.281282### State283284- Module variables reset on every hot reload. Use `$.state` or `$.store`.285- `/clear`, `/resume`, and `/branch` reset `$.state` and do **not** fire286 `session.start` again. Reload saved values in a `classic.SessionStart`287 hook filtered on `{ source: ['clear', 'resume', 'fork'] }`.288- `$.store` get-then-set races between sessions. `$.fs.write` is not atomic.289290### Interface291292- A pane your mod opens by itself (timer, `turn.start`) appears only in a293 terminal 144 columns wide, 110 after the user has opened it once. Open it294 from a command or button, or check `isPlaced` in the result of `$.ui.open`.295- `focus`, `closeOnEscape`, and `holdToasts` accept only `true`. Passing296 `false` throws. Omit the field instead.297- `borderStyle: 'rounded'` draws nothing. The valid name is `'round'`.298- An invalid tree is replaced by Claude Code's own drawing, with a299 `ui.render (Pane) refused:` line. Check `e.surface` before using300 terminal-only or Desktop-only elements.301- `claude -p` and the Agent SDK run hooks but draw nothing. Fall back to a302 transcript line or a command's text reply.303- Redraws are throttled to 10 a second (30 for the visible pane). Do not call304 `invalidate` in a tight loop.305306### Development loop307308- Editing an **installed** copy does nothing. Claude Code runs a cached copy309 per version. Develop against `--plugin-dir`.310- Errors in an installed mod appear only in the debug log. Start with311 `claude --debug-file ./mod.log`, then `tail -f ./mod.log | grep my-mod`.312- A save that breaks the module keeps the last working version running, with313 `reload failed, the previous version stays loaded`.314- A mod Claude writes does not load in `claude -p`, `dontAsk` mode, an315 untrusted folder, `--safe-mode`, `--bare`, or with `disableAllHooks`.316- If the hot-reload question times out three times, it stops asking. Copy the317 mod out and use `--plugin-dir`.318- Remove any `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` left from early access. It is319 ignored now.320- In auto mode, a hook that changes a tool call's input after the classifier321 reviewed it gets the call denied. Rewrite inputs only when you must.322323## Security324325A mod is not sandboxed. It runs as you: it reads files and secrets, sees every326prompt and tool call, can approve a call before you are asked, and can spend327your usage. It cannot restyle the permission prompt. Before you install328someone else's mod, clone it and read the `hooks:` and `calls:` lines from329`claude plugin validate ./their-mod`. Look hard at `$.process`, `$.http`,330`$.fs.write`, and `tool.check`.331332## Ideas worth building333334From Ivo Kund's first look335(<https://www.ivokund.com/first-look-at-claude-code-mods-spoiler-yes-use-one-now/>)336and Anthropic's samples:337338- A run-board pane that shows workflow steps and escalations while a long job runs.339- Clickable `#1234` issue references in tool output (`ui.render` on `ToolResult`).340- An account rotator (<https://github.com/ivokund/claude-account-rotator>).341- A deploy watcher with a status light in the band above the prompt.342- Prose rules from `AGENTS.md` moved into deterministic `tool.call` checks.343- A queue and lock for parallel browser E2E runs.344- Anthropic samples to read first: `token-weather`, `blast-radius`, and345 `replay-theater` in346 <https://github.com/anthropics/claude-code-playground/tree/main/claude-code/mods>,347 and the built-in `diff` and `sec-default` mods in348 <https://github.com/anthropics/claude-code/tree/main/mods>.