Create a mod

• Ask Claude to write it: describe what you want in a Claude Code session
• Write it yourself: follow the tutorial to learn how a mod’s code works. You don’t need Node.js, a bundler, or a build step, because Claude Code loads .js and .ts files directly.

​

Ask Claude for a mod

​

Use the mod in other sessions

• In a session you start: in your shell, run claude --plugin-dir ~/mods/git-branch
• For other people: add it to a marketplace so they can install it

​

Sessions where a mod Claude writes can’t load

• Nobody is there to approve: the session can’t show you a prompt, as in a claude -p run or dontAsk mode
• The workspace isn’t trusted: you haven’t accepted the trust prompt for the directory
• Mods are stopped: you started with --safe-mode or --bare, you set disableAllHooks, or your organization’s managed settings block it

​

Write a mod yourself

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

• plugin.json: the plugin’s manifest
• hooks.json: points to your code file
• register.js: your code, called the hooks module

mkdir -p first-mod/.claude-plugin first-mod/hooks

New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

{
  "name": "first-mod",
  "version": "0.1.0",
  "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",
  "author": { "name": "Your Name" }
}

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

// The count, shared by the hooks below
let calls = 0

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs when the session starts, before your first prompt
  on('session.start', async ($, e, next) => {
    // Add the /tally command
    await $.command.register({
      name: 'tally',
      description: 'Show how many tool calls Claude has made',
    })
    // Let the session start as usual
    return next(e)
  })

  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    // Ask Claude Code to draw the interface again, so the new count shows
    $.ui.invalidate('ui.render')
    // Let the tool run as usual
    return next(e)
  })

  // Runs when you type /tally, and only then, because of the matcher
  on('command.run', { command: 'tally' }, async () => {
    // The text to print in the transcript
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

claude --plugin-dir ./first-mod

claude -p "/tally" --plugin-dir ./first-mod

first-mod: Claude has made 0 tool calls since this mod loaded

  // Runs each time Claude Code draws the spinner
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    // Keep Claude Code's spinner, with the count added after its word
    return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })
  })

​

How the example mod works

• The mods API, named $: every method a mod can call to reach outside itself, in namespaces such as $.ui and $.command
• The event, named e: the event’s input as plain data, such as a tool call’s name and arguments
• The next handler, named next: a function that passes the event on to the other mods and then to Claude Code’s own behavior, and returns the result

• Observe: the session.start hook registers the command, and the tool.call hook counts the call and asks for a redraw. Both return next(e), so the session starts and the tool runs as usual.
• Answer: the command.run hook returns its own result and never calls next. The second argument to on, { command: 'tally' }, is a filter, called a matcher, so the hook runs only for /tally.
• Rewrite: the ui.render hook calls next with a copy of e whose suffix holds the count, so Claude Code draws its usual spinner with your text after the word

​

Keep working on a mod

​

Change a mod with Claude

claude --plugin-dir ./first-mod

​

Get type definitions for your version

​

Check what Claude Code reads from your 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

• Spell each mods API call in full: $, the namespace, then the method, as in $.store.get('notes'). You can pass $ to a function declared at the top level of the same file, and for a function of yours named loadNotes, the calls: line then reads $.store.get (via loadNotes). Passing $ to a method, a function defined inside the hook, or a function you import from another of your files fails validation. The read and update functions that $.state uses are the imports that can take it. Don’t assign $ or one of its namespaces to a variable, destructure it, or index it with a computed name. const ui = $.ui fails with $.ui is used as a value.
• Write the event name in each on call as a string literal, such as 'tool.call'. A variable, or a loop over a list of names, fails with the event name passed to on() is not a string literal.
• Inside register, don’t declare a second variable or parameter named on. Validation fails with "on" is declared again (shadowed).
• Import only from files inside the plugin directory, by relative path. The one bare import allowed is claude-code, for types and a few helpers.
• Use import declarations at the top of the file, as in import { name } from './file.js'. A dynamic import() fails with a dynamic import(); a hooks module imports its own files with an import declaration.
• Write every file as an ES module, with import and not require. The reference lists the file extensions Claude Code loads.

​

Test the mod

import { expect, test } from 'claude-code/testing'

test('/tally reports the tool calls the mod has seen', async ($, on) => {
  // Answer each tool call in Claude Code's place, so no tool runs
  on('tool.call', () => ({ result: 'ok' }))

  // Raise two tool calls, which the mod's tool.call hook counts
  await $.tool.call({ tool: 'Bash', command: 'ls' })
  await $.tool.call({ tool: 'Read', file_path: 'README.md' })

  // Run /tally and check the text its hook returns
  const answer = await $.command.run({ command: 'tally', args: '' })
  expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')
})

claude plugin test

tests/first-mod.test.ts:
(pass) /tally reports the tool calls the mod has seen [22.87ms]

 1 pass
 0 fail
Ran 1 test across 1 file. [0.19s]

​

Share your mod

​

Next steps

• Draw in the interface: open a pane, draw above the prompt, and add buttons and text fields
• React to events: hook tool calls, prompts, and turns
• Use the mods API: add commands and tools, call a model, and run work on a timer
• Test a mod: stub what Claude Code would answer, and test timers and drawings
• Troubleshoot a mod: the reasons a mod does nothing, and the debug log
• Read the source of built-in mods: complete plugins, each with its hooks module and tests