Claude Code mods are small TypeScript modules that run inside Anthropic's coding agent and can rewrite a prompt, hold or retry a tool call, decide a permission, and redraw parts of the interface while a session is running. They shipped in Claude Code v2.1.287, which the official changelog dates to October 1, 2026, and Crypto Briefing reported that Anthropic's ClaudeDevs account announced the feature that day. Anthropic's documentation says mods require v2.1.287 or later. This article separates what is genuinely new from what Claude Code already offered, compares the design with the extension points of other coding agents, and looks at the security trade-offs that come with running extension code in the agent's own process.
Anthropic
OpenAI
GoogleWhat a Claude Code mod is
Per the mods overview, a mod is a Claude Code plugin whose code registers event handlers, called hooks. Claude Code calls a hook when an event happens, such as a tool call, a submitted prompt or a part of the interface being drawn, and the handler can watch the event, change it, or take it over. A minimal mod is three files: a plugin manifest, a hooks configuration file whose modules entry makes the plugin a mod, and one JavaScript or TypeScript file that exports a register function. According to the creation guide, no Node.js install, bundler or build step is needed because Claude Code loads the files directly.
Three behaviors define the model:
- Middleware chain. Every hook receives the mods API, the event and a next function. Calling next passes the event along, and the last link is Claude Code's own behavior. Returning a result without calling next answers the event itself.
- Hot reload. Claude Code watches a directory loaded with the plugin-dir flag and reloads the hooks module when a file changes. A mod that Claude writes during a session loads after the user approves it, and reloads at the end of any turn that edits it.
- Distribution as plugins. Mods install with the /plugin command from a marketplace, and work in the CLI and the Code tab of the Desktop app, per the overview. Anthropic also lists three sample mods in its playground repository: token-weather, blast-radius and replay-theater.
What is new compared with existing Claude Code hooks
Claude Code already had hooks, which are configured in settings files and run shell commands, HTTP requests or prompts at fixed lifecycle points. The current hooks reference describes five handler types (command, HTTP, MCP tool, prompt and agent) with more than thirty events. Those settings hooks can already block a tool call, rewrite a tool's input, return a permission decision and replace a tool's output before the model sees it. So blocking and rewriting are not what is new.
The comparison table in Anthropic's overview draws the line differently: settings hooks, skills and MCP servers work from outside Claude Code, while a mod runs inside it. The practical differences:
- Interface control. Settings hooks cannot draw. Mods can open a pane beside the transcript, add a band above the prompt with buttons and text fields, and replace how Claude Code draws a tool row, the spinner or the question dialog. The reference lists 15 named render sites. Permission prompts are the exception: Anthropic says a mod cannot change what a permission prompt shows.
- More of the loop. Mods can hook the system prompt (named sections can be replaced or omitted), each request to the model (swap the model or effort for one request), subagent spawning, session compaction, and every row stored in the conversation.
- Shared state and no process spawn. A mod's hooks share variables in one module, so one hook can count calls while another displays the count, with no process launched per event.
- A callable API. Mods reach files, processes, the network, MCP servers and model completions through a single mods API, and every API method is itself an event another mod can intercept.
Where a mod can step into one turn
One turn of the agent loop, in order, with the event name a mod hooks at each point. Steps 3 to 6 repeat for every tool call in the turn.
Hooks form a middleware chain: each mod receives the event, can pass it on with next, and the last link is Claude Code's own behavior. Managed-settings PreToolUse hooks run before any mod's tool.call hook.
Governance, redaction and enterprise policy
Programmable harnesses matter because the agent loop is where policy can be enforced deterministically. Prompts and system instructions are advisory to a model, while a hook that denies a command or removes a credential from a tool result does not depend on the model complying. The events guide shows the pattern: a tool.call hook awaits the result of next, then returns a modified copy, which is the mechanism for stripping secrets from tool output, as early coverage described. Because state is shared, a mod can also keep an audit trail of every tool call.
The admin documentation shows how this scales to organizations:
- Managed-settings PreToolUse hooks run before any mod's tool.call hook, and their blocks are final.
- A built-in guard named sec-default loads ahead of user-installed mods when a machine has managed settings or a user signs in on a Team or Enterprise plan. It protects what the organization manages, such as managed hooks, the system prompt and managed instructions.
- Administrators can set allowManagedModsOnly so that only organization mods load, use prependPlugins and appendPlugins to order mods, and write a policy mod that receives a plugin.register event for each mod about to load and can refuse it, for example because its code calls process.run.
A mod is code that runs with your permissions.
Anthropic, Claude Code mods overview
How other coding agents expose extension points
Several competing agents document hook systems. The pages reviewed for this article describe scripts, MCP tools or model-evaluated prompts that run outside the agent's interface, and none describes in-process interface rendering, which makes mods an architectural outlier.
| Agent | Documented extension model | Notable detail |
|---|---|---|
| Claude Code mods | In-process TypeScript or JavaScript hooks, hot-reloaded | Can draw panes, bands and replace rows |
| OpenAI Codex | Hooks defined in hooks.json or config.toml, with command and MCP tool handlers | Documentation says prompt and agent handlers are parsed but skipped; PreToolUse can rewrite a call via updatedInput |
| Gemini CLI | Hooks in settings.json, command handler only | Docs list events such as BeforeModel, BeforeTool and AfterTool; exit code 2 blocks |
| Cursor | Hooks in hooks.json with command and prompt handlers | Docs describe permission hooks that can return updated_input |
Gemini CLIThe Gemini CLI documentation also states that hooks execute arbitrary code with the user's privileges and fingerprints project-level hooks so that changes trigger a trust warning. Claude Code has an analogous control in the trust prompt, because no mod loads in an interactive session until the user accepts it for that directory. The comparison covers documented hook mechanisms only. Each vendor also offers skills, plugins and MCP, and the event sets of Claude Code's settings hooks, Codex and Gemini CLI overlap substantially.
Security implications
Anthropic is direct about the trade-off. Mods are not sandboxed, and the overview lists what a loaded mod can do: read and write files anywhere the user can, start programs, read environment variables and settings (which can include API keys), see every prompt and tool call, rewrite them, approve a tool call before the user is asked, and spend the user's model usage. If Claude Code's sandboxing is on, it isolates the Bash commands Claude runs, while a process a mod starts runs outside it.
Several design details are worth understanding before deploying mods:
- Fail-open by default. If a hook throws or times out before calling next, Claude Code skips it and the next handler runs. A guard mod therefore needs a catch handler that returns a deny, otherwise the command it was meant to block proceeds.
- Pattern matching is a reminder, not a wall. Anthropic's own example pattern for risky commands matches rm -rf and force pushes but, as the docs note, misses other spellings such as git push with the short force flag.
- Deny rules do not cover mod internals. Where the guard loads, a user's mod cannot approve a call a deny rule refuses. But with a Read rule denying a file, a mod can still read that file through its own file API, according to the admin page.
- Approval power. A user-installed mod can approve a call that an ask rule would prompt for, or that a non-managed PreToolUse hook blocked.
- Static review exists. Running claude plugin validate on a plugin lists the events it hooks and the API calls it makes, which lets a reviewer see, without running it, whether a mod touches files, processes or the network.
What to watch
- Supply chain. Mods ship through the same marketplaces as other plugins, so trust decisions move from reading a script to vetting an extension author. Our coverage of the Claude Marketplace and the Claude Security plugin shows how quickly that surface is growing.
- API stability. Anthropic says events and methods can change between releases and tells authors to trust the type files generated for their version, so mods may need maintenance.
- Surface differences. Mods drawn in the terminal and Desktop app do not render in the VS Code chat panel or in headless runs, though hooks still execute there, per the overview.
- Convergence. Whether other agents add in-process extension layers, or Anthropic's mods settle into a common standard, will shape how portable agent governance becomes. Teams that switch between coding agents, including through model-agnostic tools such as Metir, may find that policy written as plain permission rules ports more easily than policy written as mod code.
For background on the underlying product, see our Claude Code guide. The central point of the launch is that Claude Code's extension layer has moved from scripts around the agent to code inside it, which raises both what governance and customization can do and how much trust an extension requires.
Sources:
- Create a mod, Claude Code Docs
- Mods overview, Claude Code Docs
- React to events with a mod, Claude Code Docs
- Mods reference, Claude Code Docs
- Manage mods for your organization, Claude Code Docs
- Hooks reference, Claude Code Docs
- Anthropic opens Claude Code to mods that rewrite its own functions, Crypto Briefing
- Anthropic introduces mods for customizing Claude Code, Complete AI Training
- Claude Code changelog, Claude Code Docs
- Hooks, OpenAI Codex documentation
- Gemini CLI hooks, Gemini CLI documentation
- Hooks, Cursor documentation
Image credits
Header and in-body photographs: Dario Amodei, CEO of Anthropic, speaking at TechCrunch Disrupt 2023, by TechCrunch via Wikimedia Commons (header file, in-body file), licensed under CC BY 2.0. The images show a 2023 event and not the Claude Code mods launch. Both images were reviewed before use.