Mods overview

A mod is a plugin whose code runs inside Claude Code. It is a JavaScript or TypeScript module of event handlers: Claude Code calls them when something happens (a tool call, a submitted prompt, part of the screen being drawn) and each handler can watch the event, change it, or take it over entirely. That makes mods the way to add genuinely new features to Claude Code itself, like a pane that charts context usage or a guard that pauses a risky command and asks you first.

Note: Claude Code's existing hooks also fire on events, but they are shell commands, HTTP requests or prompts configured in a settings file. A mod's handlers are functions running in-process. Both are called "hooks". On these mods pages, "hook" means a mod's handler and the settings-file kind is a settings hook.

What mods can do that nothing else can

Settings hooks, skills, status lines and MCP servers all work from the outside: they run a script, or hand Claude text or tools. A mod runs inside, so it can:

• Draw interactive UI: a pane beside the transcript or a band above the prompt, with tabs, buttons and text fields. See /docs/plugins/mods/interface.
• Redraw Claude Code's own UI: restyle or replace a tool call row, the spinner, or the dialog Claude uses to ask questions.
• Step into a tool call or model request: hold a call while asking the user, answer it without running the tool, or route one request to a different model. See /docs/plugins/mods/events.
• Run code on a command instantly: a /command that runs your function with no Claude turn, even while Claude is busy. See /docs/plugins/mods/api.
• Share state across hooks: variables in the module are shared, so one hook can count edits while another displays the count.

Mods work in the Claude Code CLI and the Code tab of the Claude Desktop app. Organisations can control them centrally; see /docs/plugins/mods/admin.

A complete small mod

A mod needs three files:

edit-meter/
├── .claude-plugin/plugin.json   # ordinary plugin manifest
└── hooks/
    ├── hooks.json               # { "modules": ["./register.js"] }
    └── register.js              # the hooks module: your code

The modules key in hooks/hooks.json is what turns a plugin into a mod. Here is a full register.js that counts how many files Claude edits and shows the number beside the spinner:

// Shared between the two hooks
let edits = 0

export function register(on) {
  // Only Edit and Write calls reach this hook
  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
    edits += 1
    $.ui.invalidate('ui.render')   // ask for a redraw so the number updates
    return next(e)                 // let the edit happen as normal
  })

  // Every time the spinner is drawn, keep it but add our text after its word
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · ' + edits + ' edits…' } })
  })
}

While Claude works you see something like Thinking · 3 edits…. Building this step by step is the subject of /docs/plugins/mods/create.

Observe, rewrite or answer

Claude Code runs your hook before it acts, so the hook decides what happens:

Anything beyond the module's own code (drawing, adding a command, calling a model, reading a file, running a process, making a network request) goes through the mods API, the $ argument. There is no other route, which is why Claude Code can list exactly what a mod does before you install it.

Getting a mod

• Built in. Some Claude Code features are already mods, such as /diff. See below.

• Ask Claude. Describe what you want in a session and Claude writes it using the built-in plugin-authoring skill. See /docs/plugins/mods/create.

• Install one. Mods install as plugins from a marketplace:

  /plugin install edit-meter@acme-plugins
  

  Copy

  or claude plugin install edit-meter@acme-plugins in your shell. Scopes, updates and marketplaces work exactly as described in /docs/plugins/install. If you install from the shell with a session open, run /reload-plugins in it.

Sample mods

Anthropic publishes unsupported samples in the claude-code/mods folder of the anthropics/claude-code-playground repository on GitHub, each a complete plugin with a README:

• token-weather: a context-window "forecast" above the prompt.
• blast-radius: holds risky shell commands such as rm -rf or a force push, shows what they would change, and offers proceed or cancel buttons.
• replay-theater: a /replay command that steps through the file edits from the last turn.

To try one, clone the repo and load the mod's folder with --plugin-dir. To keep one, add the clone's claude-code/mods folder as a marketplace and install from claude-code-playground-mods. That marketplace points at your clone, so moving or deleting the clone breaks it.

Deciding whether to trust a mod

Warning: A mod is code running with your permissions. Install only from authors and marketplaces you trust.

Once loaded, a mod can:

• act as you: read and write any file your account can, start programs, make network requests;
• read secrets: environment variables and settings files, including API keys kept there;
• see the session: every prompt and every tool call;
• change the session: rewrite a prompt or tool call, submit a prompt as if you typed it, message another of your sessions;
• act without asking: approve a tool call before you are prompted;
• spend usage: call a model on your plan or API key.

Mods are not sandboxed. With sandboxing on, Claude's Bash commands are isolated, but processes a mod starts run outside. A mod that approves tool calls can approve something an ask rule would prompt for, or that one of your own PreToolUse hooks blocked; /docs/permissions lists the cases, including when it can override a deny rule. The one thing a mod cannot restyle or alter is the permission prompt.

Inspect before installing

Get the files (clone the repo) and run:

claude plugin validate ./edit-meter

The hooks: and calls: lines list every event the mod handles and every mods API method it calls, without running any of its code. /docs/plugins/mods/admin shows which calls deserve a closer look.

Turning mods on and off

Mods are on by default from Claude Code v2.1.287 in the terminal and v2.1.286 inside the Desktop app. Check with claude --version, or /status in a local Desktop session (the Claude Code row).

disableAllHooks and an organisation's allowManagedModsOnly stop the mod code but leave the rest of its plugin (skills, commands, agents, MCP servers) loaded. Organisation controls start at /docs/plugins/mods/admin. To check whether mods can load at all, see /docs/plugins/mods/troubleshoot.

Note: If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it. From v2.1.287 it is ignored, so setting it to 0 does not keep mods off.

Which mods did this session load?

Run /plugin. A dim line under the tabs reads something like 1 mod active · edit-meter. If a mod you expect is missing, go to /docs/plugins/mods/troubleshoot.

Where mods run

Hooks run wherever the plugin loads. Drawing only appears in the terminal and the Desktop app.

A drawing mod can check which app it is in and fall back to a transcript line or command reply where nothing draws.

Mods versus the alternatives

All four can live in one plugin. My own rule: if a settings hook can do it in ten lines of bash, I do not write a mod. Mods earn their keep when you want UI or need to hold and resume an event.

Mods built into Claude Code

Some built-in features are mods. Run /plugin, open Installed, and look under Built-in. They cannot be updated or uninstalled, and the mods active line does not count them.

disableAllHooks, --bare and --safe-mode do not stop built-in mods.

The source of several built-ins is public in the mods folder of the anthropics/claude-code repository on GitHub, each with tests: diff (buttons bound to keyboard actions, self-managed scrolling), agents-md (with a userConfig option), sec-default (a model for policy mods) and telemetry (adds methods other mods can call, with types). Reading diff taught me more than any page.

Related

• Create a mod
• Draw in the interface
• React to events
• Mods reference
• Manage mods for your organisation