Claude Code 2.1.287 landed on October 1 with a one-line changelog entry that undersells it: "Added Claude Mods: plugins may now modify deeper behavior." A mod is a plugin made of JavaScript or TypeScript event handlers that run inside the Claude Code process. When an event happens, a submitted prompt, a tool call, a piece of the interface being drawn, the handler can watch it, change it, or take it over entirely.
I write and sell agent config kits, so my first question on reading the docs was not "what can I build." It was "what does this do to the enforcement layer I already ship." The answer is mixed, and one sentence in the docs changes how you should think about permission rules.
What actually shipped
Mods are not a new plugin format. They are a new plugin capability: handlers in the same process as the agent, called on lifecycle events. The changelog puts it as plugins modifying "deeper behavior."
Three things make this different from everything we already had:
- A settings hook runs a shell command or HTTP request outside the process. A mod runs inside it.
- A mod can draw real interface: panes beside the transcript, bands above the prompt, buttons, custom
/commandsthat run without a model turn. - Handlers in one mod share state, so one hook can count tool calls while another displays the count.
Anthropic used this mechanism to build features you already use. The /diff command is a mod (cc-plugin-diff). AGENTS.md support is a mod (cc-plugin-agents-md). The release also ships an opt-in side agent mod, "You should know," which watches longer tasks and surfaces risks, currently limited to first-party sessions with telemetry on.
What a mod can reach
This is the part to read slowly. The docs are unusually direct: a mod is not sandboxed, and once loaded it can:
- Read and write files anywhere your user account can, and start processes
- Read environment variables and settings files, including API keys kept there
- See every prompt you send and every tool call Claude makes
- Approve a tool call before you are asked
- Call a model on your plan or API key
There is a sandbox detail worth flagging: if you turn on sandboxing, it isolates the Bash commands Claude runs, but a process a mod starts runs outside it. Your sandbox config does not contain a mod.
The sentence that changes your enforcement model
Here is the line from the docs that made me sit up: a mod that approves tool calls can approve one that an ask rule would prompt for, or that one of your own PreToolUse hooks blocked.
Read that again if you have a deny in your permissions config. The settings-file rules I described in Config files vs hooks: where agent enforcement actually belongs assume the settings file is the outermost wall. With mods, code loaded into the process sits outside that wall. Your PreToolUse hook is still worth having, it is just no longer the last line of defense, it is one layer in a stack where the newest layer can override it.
The one thing a mod cannot touch is the permission prompt itself. It can approve around the prompt, but it cannot redraw what the prompt shows you.
Mods vs the mechanisms you already have
The docs include a comparison table that matches how I would decide:
| Need | Right tool |
|---|---|
| Block, allow, or log an event with a script you have | Settings hook |
| Stop pasting the same instructions into chat | Skill |
| Give Claude access to an external system | MCP server |
| Draw a pane, add a command, rewrite an event in flight | Mod |
For config work, the practical split is this. Instructions and conventions stay in your rules files, because a mod never changes what Claude knows, only what happens to events. Enforcement stays in settings hooks and permission rules, except now you also need to inventory which mods are loaded, because they can override both. If you want a chart of context usage per request, that is a mod, not a rules file.
Where mods actually run
The event handlers run everywhere the plugin loads: terminal, VS Code extension chat, claude -p, the Agent SDK, cloud sessions. The drawing layer is narrower: panes and bands only appear in the terminal and the Desktop app's Code tab. A WSL session in the Desktop app loads no plugins at all.
That split matters if you build one. A guard-style mod works in CI (claude -p) and in the SDK, but anything you draw is terminal-only, so the docs suggest falling back to a transcript line in other contexts.
How to trust one
You cannot rely on reputation alone here. Before installing, you can list what a mod does without running it:
git clone <mod-repo>
claude plugin validate ./mod-dir
That prints the events it handles and what it asks Claude Code to do, such as read a file or make a network request. Installing is the same plugin flow as before:
claude plugin install token-chart@your-org
# inside a session: /plugin install token-chart@your-org
# after installing from the shell into a live session: /reload-plugins
For trying samples without committing, Anthropic shares token-weather, blast-radius, and replay-theater in the claude-code-playground repo, loadable per session with --plugin-dir. The blast-radius sample is the one I would hand a team: it holds risky shell commands like rm -rf and force pushes, shows what they would change, and offers proceed or cancel buttons.
Organizations get a guard rail: the built-in cc-plugin-sec-default mod keeps admin-managed settings apart from what individual users install, and admins can control mods through managed settings. If you run a fleet of developer machines, that is the piece to read first.
What I am putting in my own kit
I am not rewriting my rules files for this. Rules files still do what they did yesterday: they shape behavior, and seven reasons your agent ignores them have not changed. What I am adding is a preflight step, the same discipline I recommended after 2.1.282 changed what a cloned repo could set: run /plugin, read the Installed tab, and diff it against what your team standardized on. A mod that quietly approves past your ask rules is the new way a "clean" setup drifts.
The configs in AgentConfig Studio ($29) ship with permission rules and hooks already separated by layer, so adding a mod inventory step is a two-line change to the preflight. If you want to audit an existing setup instead, Verify First (€19) walks a repo and tells you which files actually load. The free Next.js sample kit shows the layered structure without the paid pieces.
Mods are the most interesting thing Claude Code has shipped in weeks, and the safest posture is the boring one: validate before install, inventory after, and keep your real walls outside the process.
Top comments (0)