Claude Mods: change how Claude Code works, from the inside

What a mod can do

Mods run inside Claude Code, in its own process. That sets them apart from settings hooks, skills, and MCP servers, which all work from outside. According to the official mods overview, a mod can:

• Draw an interface you can use — a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields.
• Redraw Claude Code’s own UI — replace or restyle parts Claude Code draws itself, like a tool call’s row or the spinner.
• Step into a tool call or a request — hold a risky command while it asks you a question, answer without running the tool, or send one request to a different model.
• Run your own code on a command — a /command that runs your function instantly, with no Claude turn.
• Share data between hooks — hooks in the same file share variables, so one hook can count tool calls while another shows the count beside the spinner.

In Anthropic’s announcement, the examples are concrete: rewrite a prompt before it reaches the model, block, rewrite, or retry a tool call, approve or deny a permission request, and redact secrets from tool output before Claude reads it.

Requirements & how mods are enabled

• Terminal: Claude Code v2.1.287 or later. Check with claude --version and update if older.
• Desktop app: mods work in the Code tab from v2.1.286. Check the Claude Code row of /status.
• Mods are on by default. There is nothing to enable. (If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it — v2.1.287+ ignores it.)

Source: Turn mods on or off — Claude Code Docs

How to install a Claude Code mod

A mod installs as a plugin, from a marketplace. You give the plugin’s name, an @, and the marketplace’s name — in a session with /plugin install token-chart@your-org, or from your shell with claude plugin install token-chart@your-org. If you install from the shell while a session is open, run /reload-plugins to load it.

Try an official sample mod (no marketplace needed)

Anthropic publishes sample mods in the claude-code/mods directory of the claude-code-playground repository. To try one for a single session:

git clone https://github.com/anthropics/claude-code-playground.git
cd claude-code-playground/claude-code/mods
claude --plugin-dir ./token-weather

To keep one, add the folder as a local marketplace and install from it:

claude plugin marketplace add ./
claude plugin install token-weather@claude-code-playground-mods --scope user

To confirm which mods a session loaded, run /plugin — a dim line under the tabs lists them, like 1 mod active · first-mod.

Sources: Install or update a mod · claude-code-playground README

Build your first mod (minimal example)

A mod is a plugin whose code registers event handlers, called hooks. A small mod has three files (from the official docs):

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

This complete register.js counts the tool calls Claude makes and shows the count beside the spinner, so you watch it read Thinking · tool calls: 1…, then 2…:

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

A hook can observe an event and let it continue, rewrite it, or answer it so the usual behavior never runs. To do anything outside its own code — draw, add a command, call a model, read a file — a hook calls the mods API, which is also what lets Claude Code list what a mod does before you install it.

Source: How a mod works — Claude Code Docs (the example above is quoted from that page)

Mod list & where to find more

Anthropic’s sample mods

Source: anthropics/claude-code-playground · claude-code/mods

Mods built into Claude Code

Some of Claude Code’s own features now ship as mods — you can see them in /plugin → Installed → Built-in:

Source: Mods built into Claude Code · some built-in mod source is public in the mods directory of the Claude Code repository

Official resources

• Customize Claude Code with mods — Anthropic’s announcement (Oct 1, 2026)
• Mods overview — the official documentation starting point
• claude.dev/mods — official mods page
• anthropics/claude-code-playground — official sample mods

Where mods run

Source: Where mods run — Claude Code Docs

Security: read this before installing any mod

A mod is code that runs with your permissions, inside Claude Code. The docs are explicit: mods aren’t sandboxed, and once loaded a mod can:

• Act on your machine as you — read and write files anywhere your account can, start programs, make network requests.
• Read your secrets — environment variables and settings files, including any API key kept in either.
• See your session — every prompt you send and every tool call Claude makes.
• Change your session — rewrite a prompt or tool call, submit a prompt as if you had typed it, or message another session.
• Act without asking — approve a tool call before you’re asked.
• Spend your usage — call a model on your plan or API key.

Before installing, review the plugin. Get its files (for example by cloning its repository) and run:

claude plugin validate ./some-mod

The hooks: and calls: lines in the output list the events the mod handles and what it asks Claude Code to do — without running it. Install mods only from authors and marketplaces you trust.

Source: Decide whether to trust a mod

FAQ

Sources: Anthropic announcement · Official mods documentation