Claude Code mods, explained: what Anthropic's new extension layer can do, where it runs, and the security trade-off

On October 1, 2026, Anthropic added mods to Claude Code, its agentic coding tool. A mod is a plugin made of JavaScript or TypeScript functions that Claude Code calls from inside its own process when something happens: a tool call, a submitted prompt, or part of the screen being drawn. Each function can watch the event, change it or take it over. That puts mods deeper inside Claude Code than any of its earlier extension mechanisms. Unlike the settings hooks, skills and MCP servers that came before, a mod can redraw the interface, and it can approve or refuse a tool call before you see a prompt.

This explainer is based on Anthropic's announcement, documentation and changelog, and on the npm registry.

What shipped, and when

Anthropic announced mods in a post on its Claude blog on October 1, 2026. The same day, version 2.1.287 of the @anthropic-ai/claude-code package went out on npm. According to Anthropic's documentation, mods need Claude Code v2.1.287 or later in the terminal. The Code tab of the Claude Desktop app ships its own copy of Claude Code, and mods work there from v2.1.286.

One detail matters if you're waiting for mods to appear. Claude Code has release channels. Anthropic's docs say the Homebrew claude-code cask follows a stable channel that's "typically about a week behind." According to the npm registry on October 9, 2026, the stable tag pointed to 2.1.286, while latest was 2.1.295. If you're on the stable channel, you probably don't have mods in the terminal yet. Run claude --version to check.

Last verified: October 9, 2026.

Some of Claude Code's own features are themselves built-in mods. The /diff pane ships as a built-in mod (cc-plugin-diff), and so does the code that reads AGENTS.md files (cc-plugin-agents-md). The CLAUDE.md and AGENTS.md guide covers that part in detail. Anthropic says more built-in features will move to mods over time.

How a mod works

A mod is an ordinary Claude Code plugin with one extra piece: a "hooks module". A minimal mod has three files:

first-mod/
├── .claude-plugin/
│   └── plugin.json      # the plugin manifest
└── hooks/
    ├── hooks.json       # {"modules": ["./register.js"]} makes it a mod
    └── register.js      # your code

The hooks module exports a register(on) function. Each call to on('event.name', handler) registers a hook. Every handler gets three arguments:

• $: the mods API, Claude Code's methods grouped into namespaces such as $.ui, $.command, $.fs, $.http, $.process and $.model.
• e: the event's input, as frozen plain data.
• next: the next handler in the chain. It works like web middleware, so calling next(e) passes the event on to other mods and then to Claude Code's own behavior.

That gives a hook three choices, according to the mods overview. It can observe the event and call next(e). It can rewrite the event and call next() with a changed copy. Or it can answer the event itself and skip next entirely, for example by refusing a command.

Anthropic's tutorial example counts tool calls and shows the count next to the spinner:

let calls = 0
export function register(on) {
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

There's no build step. Claude Code loads .js and .ts files directly.

What events a mod can hook

The mods reference groups the events into families:

• Tools: tool.call runs before a tool runs. tool.check decides allow, ask or deny. tool.describe can rewrite a tool's description.
• Prompts and context: prompt.submit and prompt.compose. There's also prompt.section, which can rewrite or remove sections of the system prompt.
• Commands and config: command.run, which adds /commands that run your code instantly with no model turn, and config.set.
• Turns and sessions: turn.step can, for example, send one request to a different model or effort level. Also session.start, session.compact and messages between sessions.
• Subagents: agent.spawn can change a subagent's model or refuse to start it.
• Interface: ui.render covers panes beside the transcript, a band above the prompt, and Claude Code's own rows, spinner and question dialogs.
• Settings hooks: the existing shell-command hooks surface as classic.<Event>, such as classic.PostToolUse.

Where mods run

Mod hooks run in every kind of session that loads the plugin. That includes claude -p, the Agent SDK, the VS Code extension and cloud sessions. Anything a mod draws, though, only appears in the terminal and the Desktop app's Code tab. Plugins, and so mods, aren't available in WSL sessions in the Desktop app.

How to use one

Install a mod someone else wrote. Mods install like any plugin, from a marketplace: /plugin install token-chart@your-org inside a session, or claude plugin install token-chart@your-org in your shell. If you install from the shell while a session is open, run /reload-plugins. Anthropic has published unsupported samples in its claude-code-playground repository, including token-weather, blast-radius and replay-theater. token-weather shows a context-window "forecast" above the prompt. blast-radius holds a risky command like rm -rf or a force-push and shows what it would change. replay-theater adds a /replay command that steps through Claude's last edits.

Ask Claude to write one. You can describe the mod in a session, for example "make a mod that shows the current git branch above the prompt". Claude then uses a built-in plugin-authoring skill to write it into ~/.claude/dev-mods/<session-id>/. Claude Code asks whether to turn on hot reloading for the session. If you agree, the mod loads at the end of the turn and reloads whenever Claude changes it. These session mods get deleted after the cleanupPeriodDays retention period, so copy the directory out if you want to keep one.

Write one yourself. Load a directory for one session with claude --plugin-dir ./first-mod. Claude Code watches that directory and hot-reloads the module when you save. It also writes TypeScript declaration files for your exact version into .claude-plugin/types/. Anthropic says to trust those files over its web docs when the two disagree.

Check and test. Two shell commands do the checking:

• claude plugin validate ./first-mod statically lists the events a mod hooks (hooks:) and the API methods it calls (calls:), without running it.
• claude plugin test runs *.test.ts files with no session, sign-in or network.

Turn mods off. You have three options, from narrowest to broadest:

• Disable one mod's plugin in /plugin.
• Start a session with --safe-mode to skip every installed mod for that session.
• Set "disableAllHooks": true in ~/.claude/settings.json to stop installed mods everywhere. That also stops your settings hooks and status line.

None of these stops the built-in mods.

Limits

The reference documents hard limits. A hook that runs past a time limit is skipped, and a call that goes over a size limit is rejected.

Last verified: October 9, 2026 against the mods reference. Anthropic notes that events and methods "can change between releases."

There are some practical limits too. A mod Claude writes won't load where nobody can approve it, such as claude -p or dontAsk mode, or in an untrusted workspace. Static analysis also constrains how you write code: event names must be string literals, and you can't alias $ or its namespaces.

Plans and availability

Mods are part of Claude Code itself. Anthropic hasn't announced a separate price or a plan restriction for them. The blog post says they're "available today in the Claude Code CLI and desktop app." Claude Code itself is included on Pro, Max, Team and Enterprise plans, and with an Anthropic Console (API) account. It isn't included on the Free plan, according to Claude's pricing page. Mods that call a model through $.model.complete spend your plan's usage or API credits, like any other Claude Code request.

Organizations get extra controls, according to the admin documentation:

• On machines with managed settings, or for users signed in with a Team or Enterprise plan, a built-in guard mod called sec-default loads ahead of any mod a user installs. Anthropic says it blocks risky actions such as overriding permission deny rules.
• allowManagedModsOnly limits loading to the organization's own mods.
• prependPlugins and appendPlugins set the order mods run in.
• disableSideloadFlags rejects --plugin-dir.

The security trade-off

This is the part to read twice. Anthropic's own docs say a mod runs with your permissions and isn't sandboxed. Once loaded, it can:

• read and write any file your account can, start processes and make network requests;
• read environment variables and settings files, including API keys;
• see every prompt and tool call;
• approve a tool call before you're asked.

If you turn on Claude Code's Bash sandbox, it doesn't cover processes a mod starts. Anthropic's documentation describes one hard boundary: a mod can restyle most of the interface but can't change what the permission prompt shows you.

That's a meaningful expansion of what a third-party plugin can do. Before mods, a malicious skill could only ask Claude to do something. A malicious mod can do it directly. Anthropic's mitigations are real but partial:

• claude plugin validate lets you see a mod's declared events and calls before you install it.
• Static-analysis rules make those calls hard to hide.
• sec-default protects organizations' managed settings.

None of that helps an individual user who installs a mod from an unknown marketplace without reviewing it. Treat a mod like a VS Code extension or an npm package with a postinstall script, and review it before running it. For the broader case on why agents shouldn't run unattended, see our piece on sandboxing and real incidents.

Where mods fit

Anthropic's docs give a simple rule for choosing between Claude Code's extension mechanisms:

• Skills are Markdown instructions Claude reads.
• Settings hooks run a shell script on a lifecycle event.
• MCP servers give Claude tools that reach external systems. See our MCP explainer.
• Mods are for when you need to draw something, add an instant command, or rewrite an event inside the process.

Most teams will still get more out of a short, specific CLAUDE.md than out of a mod. Mods are for the cases where instructions aren't enough.

Neither OpenAI's Codex nor Cursor documents an equivalent in-process extension API in the material we reviewed. Both support MCP and instruction files such as AGENTS.md. We compare the three tools' features, prices and limits in Claude Code vs Codex vs Cursor.

What we don't know yet

• Performance cost. Anthropic hasn't published how much overhead a stack of mods adds to each tool call or redraw.
• Ecosystem quality. The official directory accepts mod submissions, but it's too early to say how Anthropic reviews them.
• API stability. Anthropic says events and methods may change between releases. Expect mods written in October 2026 to need maintenance.