Anthropic's Claude Code Mods Let Developers Rewrite the Agent From Inside

Anthropic has added Mods, an extensibility layer for Claude Code. Each mod is a small TypeScript module that can rewrite prompts, intercept tool calls, render interface components, register commands and tools, or replace built-in features. Mods work in the CLI and desktop app and ship through the existing /plugin workflow.

Earlier settings hooks could observe events and invoke external scripts, but they could not rewrite events, draw interface elements, or replace features. Mods add those capabilities, enabling extensions such as confirmation gates for destructive shell commands, persistent usage displays, and custom review panes.

Middleware inside the agent

A mod exports a register(on, options) function that attaches handlers to events such as tool.call, prompt.submit, turn.start, turn.complete, session.start, command.run, and ui.render. Each handler receives an API object, an event payload, and a next function. The resulting control flow resembles Express middleware:

• Observe: Call await next(e), then inspect the result.
• Rewrite: Call next({ ...e, command: safer }) to change the payload passed to downstream handlers.
• Short-circuit: Return { deny: "..." } without calling next.

When multiple mods handle the same event, Claude Code runs them in load order. The first handler sees the incoming event first and the final result last, allowing an administrator-controlled security mod to wrap extensions loaded afterward.

Settings hooks launch a process and exchange JSON over standard input and output for each event. A mod loads once and persists for the session, so it can retain state, subscribe to interface redraws, register slash commands, and expose tools that the model can call.

Three useful design patterns

Anthropic’s getting-started guide includes three reference implementations that demonstrate the main APIs:

• Token Weather reads $.session.usage() after each turn and renders a status line above the prompt. It shows context usage, token count, a 12-turn sparkline, and the change since the previous turn in roughly 80 lines of code.
• Blast Radius intercepts Bash calls and classifies commands such as rm -rf and git reset --hard. It runs dry-run checks through $.process.run, then opens a side pane with Proceed and Cancel controls.
• Replay Theater records Edit and Write calls during a turn. Its /replay command presents the resulting diffs one at a time in a docked pane.

Session data belongs in $.state because hot reloading starts the module again, reruns register, and emits another session.start event. Reads from $.state inside a render hook also create subscriptions, so later writes trigger redraws without manual invalidation.

Claude can scaffold the code

Claude Code can generate a mod from a natural-language request and hot-reload it into the current session. Developers can describe the behavior, approve hot reloading, and refine the result with follow-up requests such as changing thresholds or adding estimated cost.

Each load writes current type declarations to the plugin’s .claude-plugin/types/ directory. Editors and tsc therefore use definitions that match the installed Claude Code API.

• claude plugin validate reports the events a module handles, the $ methods it calls, and the state keys it reads or writes.
• claude plugin test runs *.test.ts files against the Claude Code runtime. Test hooks run after the mod’s hooks, allowing tests to stub downstream responses.

Core features move into plugins

Anthropic has also implemented some built-in Claude Code features as mods. The /diff feature can be disabled through /plugin or replaced with another implementation. Support for AGENTS.md uses the same system, with source code available under mods/ in the Claude Code repository.

Moving features out of the core gives developers more control over Claude Code’s behavior while letting installations load only the components they need.

Mods inherit full process access

Mods run with the same access to the machine as Claude Code. They are unsandboxed and should receive the same scrutiny as any locally installed program. A mod can read files, start processes, and inspect information passing through the agent.

Blast Radius illustrates the limits of advisory safeguards. It inspects command text, so aliases, wrapper scripts, and shell substitutions such as $(...) can bypass its classifications. Enforce non-negotiable restrictions with Claude Code permission rules or operating-system controls.

Team and Enterprise plans, along with machines that use managed settings, load a built-in mod named sec-default before user-installed mods. It prevents extensions from performing actions such as overriding permission deny rules. Administrators can install their own first-loading mod while retaining sec-default in the chain. Existing plugin marketplace allowlists and blocklists also apply.

What developers can build

Mods expose the agent’s event flow and interface to code that teams can inspect, version, test, and distribute. Practical uses include:

• A prompt.submit handler that adds team conventions to each request.
• A tool.call guard that requires confirmation before kubectl targets production or before terraform apply runs.
• A CI/CD pane that updates as builds and deployments change state.
• An audit mod that loads first and records calls made by later extensions.
• A cost or rate-limit display driven by $.session.usage().

Installing and publishing mods

Mods are available in the Claude Code CLI and desktop app at no additional cost. Existing extensions can be installed through /plugin or found in the Claude directory. Publishers can distribute a plugin from a GitHub repository that includes marketplace.json, while Anthropic’s playground repository provides sample mods for new projects.