Level 1 What a mod is

Mods 101

A mod is a plugin whose code Claude Code runs inside its own process. The code registers functions called hooks on named events: a tool call, a submitted prompt, a part of the screen being drawn. Each hook joins a chain in front of Claude Code's own behaviour and decides what happens next.

Three files

A small mod is a folder with three files. Nothing needs installing or building, because Claude Code loads TypeScript directly.

tool-counter/
├── .claude-plugin/
│   └── plugin.json      the plugin's manifest: name, version, description
└── hooks/
    ├── hooks.json       { "modules": ["./register.ts"] }
    └── register.ts      your code: the hooks module

The modules key in hooks.json is what makes a plugin a mod. It names exactly one file. Without it the plugin still validates, but it has no mod code. The same plugin can also carry skills, agents, MCP servers and settings hooks.

A complete mod

This is the example from the official overview. It counts tool calls and adds the count to the spinner, so while Claude works you see Thinking · tool calls: 3….

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

// Claude Code calls this once when the mod loads
export function register(on) {
  // Runs each time Claude is about to use a tool
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')   // ask for a redraw so the count shows
    return next(e)                 // let the tool run as usual
  })

  // 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 + '…' } })
  })
}

Load it for one session without installing anything:

claude --plugin-dir ./tool-counter

Run /plugin and a dim line under the tabs says 1 mod active · tool-counter. The folder is watched, so saving register.ts reloads the mod in place.

The four names

The three moves

Claude Code runs your hook before it acts on the event, so the hook decides what happens. It has three choices:

// Observe: note it, change nothing
on('tool.call', ($, e, next) => { log(e); return next(e) })

// Rewrite: the rest of the chain sees the new event
on('tool.call', { tool: 'Bash' }, ($, e, next) => next({ ...e, command: e.command.trim() }))

// Answer: return a result without calling next, so nothing beneath runs
on('tool.call', { tool: 'Bash' }, ($, e, next) =>
  /\bgit\s+push\b.*--force/.test(e.command) ? { deny: 'Ask the person to force-push themselves.' } : next(e))

A hook can also await next(e) and then change the result on its way back up, or call next twice to retry. Because each hook wraps the ones after it, the chain works like middleware in a web server.

What a mod can hook

The 2.1.296 declarations list 46 engine events, plus every settings-hook event as classic.<Event>. They fall into a few families:

Every $ call is an event too (fs.read, model.complete, http.fetch). A mod that runs earlier in the chain can watch, change or refuse what a later mod asks for.

Where mods run

A guard keeps working in headless runs. A pane doesn't appear there, so a mod that draws should check e.surface and fall back to a transcript line or a command reply.

Trust: what a mod can reach

The module itself has no ambient authority: no Node, no DOM, no file or network globals. (The docs also say no timers, but our field tests found setTimeout present on 2.1.296.) Everything that reaches outside goes through $, so the loader can read a mod's source and list what it does. Before you install one, run:

claude plugin validate ./some-mod

The hooks: line lists the events the mod handles. The calls: line lists what it asks Claude Code to do, such as fs.read, process.run or http.fetch. A mod that counts tool calls and also calls http.fetch deserves a closer look.

Turning mods off

• One mod: disable or uninstall its plugin in /plugin.
• Every installed mod, for one session: claude --safe-mode.
• Every mod you installed, always: "disableAllHooks": true in ~/.claude/settings.json. This also stops your settings hooks and custom status line. What your organization manages keeps running.
• Not a switch: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS was the early-access flag. 2.1.287 and later ignore it, so setting it to 0 does not turn mods off.

Built-in mods such as /diff's pane keep running under all of these. They are listed separately in /plugin.

What to remember

1. Three files: plugin.json, hooks.json with modules, and one hooks module.
2. Every hook is ($, e, next). It can observe, rewrite or answer.
3. Everything outside the module goes through $, so claude plugin validate can list it.
4. Hooks run everywhere the plugin loads. Drawings show only in the terminal and the Desktop app.
5. A mod has your permissions. Read its calls: before you install it.