Claude Code ships mods, the same tool behind its /diff
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": trueto 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=1keeps 200K. - The OpenTelemetry
user_promptevent gainsprompt_text, a copy ofpromptfor backends that nest dotted keys. Drop or mask it wherever you drop or maskprompt. - 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.
Up next
Microsoft brings streaming MAI-Transcribe-2 to its APIs
A streaming version of MAI-Transcribe-2 is coming to Microsoft’s MAI Playground and APIs, and it brings MAI-Voice-2.1 and a Flash variant along, pitched for building conversational voice agents.
Related stories
Comments
No comments yet. Be the first.
Join the conversation
Sign in to leave a comment. It appears after moderation.

