Claude Code mods: what they are, how to build one, and 12 worth installing

01 · The canvas

Where a mod can draw

Each place a mod can draw is a render site. Claude Code fires ui.render every time it is about to draw one, and your hook returns what goes there. Some sites start empty and exist only for mods (pane, band, toast, log line, status line). Others are Claude Code's own, and a mod can restyle or replace them (spinner, tool rows, messages). Hover a zone or pick a site:

on('ui.render', { component: 'Pane' }, async ($, e, next) => {  if (e.requestId !== 'launch-codes') return next(e)  const { Box, Text, Button } = $.ui.resolve(e)  return Box({ flexDirection: 'column', children: [    Text({ bold: true, color: 'red', children: ['LAUNCH CODES REQUIRED'] }),    Button({ key: 'run', label: 'Run it', onPress: approve }),  ] })})

on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {  const { Text } = $.ui.resolve(e)  return Text({ children: ['tests · last run failed · 3 runs'] })})

$.ui.toast('burn-meter: $5.00 burned this session')

$.ui.log('Claude changed ' + e.file_path)

$.ui.status('checks: 3 passing')// shows as: ⚠ ci-watch: checks: 3 passing

on('ui.render', { component: 'Spinner' }, async ($, e, next) =>  next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } }))

on('ui.render', { component: 'ToolUse' }, async ($, e, next) => next(e))

on('ui.render', { component: 'AssistantMessage' }, async ($, e, next) => next(e))

on('ui.render', { component: 'PromptHint' }, async ($, e, next) => next(e))

In a terminal narrower than the pane needs, the pane sits above the prompt instead of beside the transcript.

02 · Capabilities

What a mod can do that hooks, skills and MCP can't

Settings hooks, skills, status lines and MCP servers all work from outside Claude Code: they run a script, or give Claude text or tools. A mod runs inside, in Claude Code's own process.

• Draw an interface you can use

  Panes beside the transcript and a band above the prompt, with tabs, buttons, text fields and selects.

• Redraw Claude Code itself

  Restyle or replace the spinner, tool rows, messages and the question dialog.

• Step into a tool call

  Refuse it, rewrite its arguments, hold it while you ask the user, or answer it without running the tool.

• Run code on a /command

  Your function runs at once, with no Claude turn, even while Claude is working.

• Share data between hooks

  Hooks in one file share variables: one counts tokens, another charts them in a pane.

Some of Claude Code's own features are already mods: /diff, AGENTS.md loading, telemetry, and the plugin-authoring skill. Run /plugin → Installed and look under Built-in.

03 · The model

Every hook does one of three things

A hook is a function you pass to on(eventName, [matcher], hook). Claude Code calls it with three arguments: $, the mods API; e, the event as plain data; and next, which passes the event on to the other mods and then to Claude Code. What you do with next decides the outcome:

let calls = 0 export function register(on) {  on('tool.call', async ($, e, next) => {    calls += 1    $.ui.invalidate('ui.render')   // redraw, so the new count shows    return next(e)                 // let the tool run as usual  })}

on('prompt.submit', async ($, e, next) => {  if (!/\bPR\b|pull request/i.test(e.text)) return next(e)  const r = await $.process.run(['git', 'branch', '--show-current'])  return next({ ...e, context: [...(e.context ?? []), 'Branch: ' + r.stdout.trim()] })})

on('tool.call', { tool: 'Bash' }, async ($, e, next) => {  if (/git push .*--force/.test(e.command)) {    return { deny: 'Force pushes are not allowed here. Push to a new branch instead.' }  }  return next(e)})

claude --plugin-dir ./first-mod

04 · No code

Make a mod with just a prompt

You don't need to know JavaScript. Describe the mod in an interactive Claude Code session and Claude writes it with the built-in plugin-authoring skill (or run /plugin-authoring yourself first). You approve the files, and the mod is live when the turn ends.

A mod Claude writes doesn't load in claude -p, in dontAsk mode, in an untrusted folder, or when mods are off (--safe-mode, --bare, disableAllHooks).

Six prompts to copy for QA work

• Test status above the prompt

  Band

  Make a mod that watches Bash commands that run tests (playwright test, vitest, jest, pytest, npm test) and shows the last result in the band above the prompt: passed or failed, plus how many runs failed this session. Show nothing until the first test run.

  Copy prompt

• Ask before destructive commands

  Question dialog

  Make a mod that holds any Bash command matching rm -rf, git reset --hard, git push --force or DROP TABLE and asks me "Run it" or "Refuse" before it runs. If I dismiss the question or nobody can answer, refuse.

  Copy prompt

• Current git branch

  Band

  Make a mod that shows the current git branch above the prompt.

  Copy prompt

• Keep production safe

  Tool check

  Make a mod that refuses Bash commands that call our production host api.example.com unless the current git branch starts with release/. Tell Claude why in the refusal.

  Copy prompt

• /bug: draft a bug report

  Command

  Add a /bug command that takes my description and turns it into a bug report with title, steps to reproduce, expected and actual result, using a small model. Print it in the transcript without starting a Claude turn.

  Copy prompt

• One-line turn summary

  Under the answer

  Make a mod that, at the end of each turn, shows one line under the answer: files changed, test commands run, and whether they passed.

  Copy prompt

Tip: end any of these with "then run claude plugin validate and add a test". Claude checks its own work, and you get a list of every event the mod hooks and every API it calls.

05 · Hands-on

Write your first mod in five minutes

first-mod/
├── .claude-plugin/
│   └── plugin.json   ← manifest
└── hooks/
    ├── hooks.json    ← "modules": ["./register.js"]
    └── register.js   ← your hooks

1. Point Claude Code at your code

   The modules key in hooks/hooks.json is what makes a plugin a mod.

   hooks/hooks.jsonjson

   {  "description": "The first-mod hooks module",  "modules": ["./register.js"]}

2. Write the hooks: a counter plus a /tally command

   hooks/register.jsjs

   let calls = 0 export function register(on) {  on('session.start', async ($, e, next) => {    await $.command.register({ name: 'tally', description: 'Show how many tool calls Claude has made' })    return next(e)  })   on('tool.call', async ($, e, next) => {    calls += 1    $.ui.invalidate('ui.render')    return next(e)  })   on('command.run', { command: 'tally' }, async () => {    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }  })   on('ui.render', { component: 'Spinner' }, async ($, e, next) => {    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })  })}

3. Load it, then check what Claude Code sees

   --plugin-dir loads the directory for one session and hot-reloads on save. claude plugin validate statically lists every event you hook and every API you call.

   terminalbash

   claude --plugin-dir ./first-mod claude plugin validate ./first-mod  ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}  ❯ ./register.js calls: $.command.register, $.ui.invalidate✔ Validation passed

4. Test it with no session, sign-in or network

   tests/first-mod.test.tsts

   import { expect, test } from 'claude-code/testing' test('/tally reports the tool calls the mod has seen', async ($, on) => {  on('tool.call', () => ({ result: 'ok' }))           // stub: no real tool runs  await $.tool.call({ tool: 'Bash', command: 'ls' })  await $.tool.call({ tool: 'Read', file_path: 'README.md' })  const answer = await $.command.run({ command: 'tally', args: '' })  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')})

   terminalbash

   claude plugin test(pass) /tally reports the tool calls the mod has seen [22.87ms] 1 pass 0 fail

claude --plugin-dir ./hello-tabs

06 · Choosing

Mod, settings hook, skill or MCP server?

They overlap, and one plugin can ship all four. Reach for a mod only when the others can't do the job.

07 · In the wild

Which problems mods actually solve

Within days of the launch, people were sharing mods on GitHub. The useful ones cluster around four pains: agents doing something irreversible, not seeing cost or context until too late, unreadable long runs, and leaking secrets on screen. These screenshots are from OneWave AI's open-source set (MIT):

launch-codesPainAn agent runs rm -rf or a force push while you look away.ModEvery risky Bash command waits for a one-time code typed from a red-alert pane.Draws: pane + question dialogburn-meterPainYou find out what a session cost after it ends.ModLive spend, 5-hour and weekly limits in the band, with a per-turn chart in a pane.Draws: band + pane + toastsagent-narratorPainLong autonomous runs are a wall of tool calls nobody reads.ModEach step in plain English, test results flagged ✗/✓, and an estimate of time saved.Draws: pane + toastboss-fightPainFixing a red test suite is a grind.ModFailing tests spawn a pixel boss that loses HP as tests turn green. Silly, but it is a live test dashboard.Draws: pane + toast + hint line

launch-codes

Screenshots: OneWave-AI/claude-code-mods, MIT License.

12 mods worth installing first

Anthropic's samples live in anthropics/claude-code-playground and are shared as-is, without support. Read any mod's source before installing it. The next section on security explains why.

08 · For testers

Mods for QA engineers: three recipes

For a QA team, a mod puts a test signal or a guard right where the agent works. That beats a dashboard in another tab or a rule in a README nobody reads.

const TEST = /\b(playwright test|vitest|jest|pytest|npm (run )?test)\b/let runs = 0, failed = 0, last = '' export function register(on) {  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {    if (!TEST.test(e.command)) return next(e)    const result = await next(e)          // run the tests first    // isError = the tool reported an error; also read the output for "N failed"    const red = result.isError || /[1-9]d* failed|FAIL/.test(result.text ?? '')    runs += 1    if (red) failed += 1    last = red ? 'failed' : 'passed'    $.ui.invalidate('ui.render')    return result                          // Claude still reads the real output  })   on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {    if (runs === 0) return next(e)         // nothing to show yet    const { Box, Text } = $.ui.resolve(e)    return Box({ flexDirection: 'row', columnGap: 2, children: [      Text({ bold: true, children: ['tests'] }),      Text({ color: last === 'failed' ? 'red' : 'green', children: ['last run ' + last] }),      Text({ dimColor: true, children: [runs + ' runs · ' + failed + ' failed'] }),    ] })  })}

const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bgit\s+push\b.*--force|\bDROP\s+TABLE\b/i export function register(on) {  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {    if (!RISKY.test(e.command)) return next(e)    let answer = 'Refuse'                               // safe default    try {      answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])    } catch {}                                          // dismissed, or nobody to ask    if (answer !== 'Run it') {      return { deny: 'The user declined this command. Ask before trying a different approach.' }    }    return next(e)                                      // permission check still runs  })}

on('command.run', { command: 'triage' }, async ($, e) => {  const r = await $.model.complete({    model: 'haiku',    system: 'Reply with one word: bug, feature, or question.',    prompt: e.args,    maxTokens: 20,    timeoutMs: 15000,  })  return { text: 'Label: ' + (r.isAnswered ? r.text.trim() : 'unknown') }})

09 · Trust

Security: a mod is code with your permissions

Mods are not sandboxed. Even with sandboxing on, a process a mod starts runs outside the sandbox. Once loaded, a mod can:

• Act on your machine as you. Read and write any file, start programs, make network requests.
• Read your secrets. Environment variables and settings files, including API keys.
• See your session. Every prompt and every tool call.
• Act without asking. Approve a tool call before you're asked, rewrite prompts, submit one as if you typed it.
• Spend your usage. Call a model on your plan or API key.

The one line it can't cross: the permission prompt is not a render site, so a mod can't change what it shows you. Before installing, list exactly what a mod does without running it:

git clone https://github.com/someone/some-mod && claude plugin validate ./some-mod# read the hooks: and calls: lines. $.process.run or $.fs.write deserve a look at the source

Turning mods off

• One mod. /plugin → Installed → disable or uninstall.
• All installed mods, one session. claude --safe-mode
• All installed mods, everywhere. "disableAllHooks": true in ~/.claude/settings.json. This also stops settings hooks and your custom status line.
• Organisations. Managed settings can limit mods to managed ones (allowManagedModsOnly).

Where mods run

10 · Watch

Four videos worth your time

Picked for different angles: setup, a fast overview, community ideas, and what can go wrong. Videos load only when you press play.

11 · Cheat sheet

Quick reference

Events and methods change between releases. Claude Code writes exact .d.ts types for your version into .claude-plugin/types/ of every mod it loads with --plugin-dir. When the types and a web page disagree, trust the types.

FAQ

Frequently asked questions