Skip to content

Claude Code

Claude Code ships mods, the same tool behind its /diff

4 min read

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →
Video: x.com

Anthropic on October 1 opened Claude Code to mods, small TypeScript modules that ship inside plugins and can change how the agent behaves, redraw parts of its interface or swap in features of your own, the company announced on X. To try one you need Claude Code 2.1.287 or later, where mods are on by default. You install them like any plugin, with /plugin in the CLI or the desktop app, and the mod API can change between releases.

Anthropic was using mods before anyone else could: the /diff pane beside the conversation and AGENTS.md support are both built as mods, with source and tests in the public anthropics/claude-code repository, according to the company’s getting-started guide. The idea first appeared as function hooks in a GitHub issue opened September 3 and picked up the Claude Mods name in Anthropic’s September 9 community update. If you want something to start from, Anthropic is adding pre-built sample mods to the Claude Code Playground repo. Or you can have Claude write the mod for you.

What mods add over hooks

A settings hook runs a shell command for each event and passes JSON over stdin and stdout. A mod gets loaded once and stays in the session. That means it can keep state, draw UI that updates as events come in, open a pane, run a process, and register a slash command or a tool the model can call.

Mod hooks form a chain, the way middleware does. Each hook receives the event and calls next(e) to hand it to the other plugins, and at the bottom of the chain Claude Code does what it would have done anyway. A hook can just watch, pass a modified event down the chain, or answer on its own without calling next. Returning { deny: "…" } refuses a tool call, and the same route lets a mod serve a command or a tool itself.

The events cover tool calls, the prompt as submitted, turns starting and finishing, the session starting and ending, slash commands, and ui.render, which fires for every piece of the interface as it is drawn. Each mod runs in its own sandbox with no DOM and no Node. Anything outside it, from the filesystem and processes to HTTP and the model, goes through the $ API.

Structurally a mod is an ordinary plugin with a .claude-plugin/plugin.json manifest. Its hooks/hooks.json lists one module under modules, and that module exports register(on, options), where each on(event, matcher?, hook) call adds a hook. The guide’s walkthrough builds Token Weather, about 80 lines that draw a live forecast of the context window above the prompt, and then tours two bigger mods, Blast Radius and Replay Theater.

You should know, with conditions

The release comes with one built-in mod, You should know, which runs a side agent that keeps an eye on the session and flags things you or Claude might miss. You turn it on with /plugin enable cc-plugin-you-should-know@builtin, and it runs only in first-party sessions with telemetry on, so the mod Anthropic picked to show off the feature is closed to anyone who keeps telemetry off.

Before you update to 2.1.287

Mods ship in a release with a long changelog, and several of its items can change your setup:

  • MCP servers on the 2025-11-25 protocol can now show URL prompts, for example to sign in. If a server stops connecting after the update, add "bareElicitationCapability": true to its MCP config entry.
  • Opus 4.7+ and Fable now use a 1M context window by default on Bedrock, Vertex, Foundry and the Claude apps gateway, with no [1m] suffix. CLAUDE_CODE_DISABLE_1M_CONTEXT=1 keeps 200K.
  • The OpenTelemetry user_prompt event gains prompt_text, a copy of prompt for backends that nest dotted keys. Drop or mask it wherever you drop or mask prompt.
  • A dangerous rm, such as one on / or the home directory, keeps its always-ask safeguard even when the same command redirects output to a ~ or wildcard path.
  • On Windows, a startup warning now says when denying the Bash tool also turns off the PowerShell tool and leaves Claude with no shell tool.

If you write mods, keep in mind that the API is tied to the build. Each time Claude Code loads a mod, it writes type declarations for that build into the mod’s .claude-plugin/types/ folder, and those declarations are the authority for that version.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.