Claude Code mods: programmable guardrails inside the agent harness

Claude Code mods are in-process TypeScript hooks that can guard, rewrite and redraw the agent, for developers who want to own their guardrails.

Picture a freelance developer running Claude Code across three client repos. She lets the agent run shell commands because approving every one kills her flow. Her safety net is a settings hook: a small script that refuses any command containing --force. It works, but it is blunt. When it fires she gets a refusal, not a view of what the command would have touched, and there is no clean way to say "yes, this time." The command that actually hurts her is the one she approves on autopilot late in the day.

Claude Code mods target that gap. According to Anthropic's mods overview, the sample blast-radius mod "holds a risky shell command, such as rm -rf or a force push, and shows what it would change, with buttons to proceed or cancel." A Latent Space essay frames mods as an early "Attention Interface": the layer that decides when the agent interrupts you, what it shows you and which decisions it needs from you. With mods, you shape that layer yourself.

What it is

Mods officially arrived in Claude Code on October 1, 2026, according to azukiazusa's hands-on write-up. Anthropic's getting-started guide defines a mod as a Claude Code plugin whose behavior lives in a JavaScript or TypeScript module. The plugin's hooks/hooks.json names one module under modules. That module exports register(on, options), and on(event, matcher?, hook) adds a hook. Every hook has the same shape, per the guide:

on("tool.call", { tool: "Bash" }, async ($, e, next) => {
  // $ the mods API: ui, session, state, store, fs, process, clock, http, tool, command, model, ...
  // e this event's input, as plain data
  // next passes e to the other plugins and then to Claude Code's own behavior
  return next(e);
});

Hooks chain like middleware, and each can make one of three moves. It can observe (await next(e), then look at the result), rewrite (pass a modified event to next) or answer (return { deny: "…" } without calling next). The events cover tool calls, the submitted prompt, turns starting and finishing, session start and end, slash commands, and ui.render. Mapped to the lede: answer is the guard, the $.ui surface draws the proceed and cancel buttons, and observe lets you count what was blocked. azukiazusa built that combination, a mod that blocks dangerous Bash commands and shows a running count above the prompt.

According to the docs, mods differ from settings hooks because they run inside Claude Code. They can draw panes and bands, redraw Claude Code's own interface, hold a tool call while asking you a question, and add /commands that run without a Claude turn. No Node.js, bundler or build step is needed, Better Stack notes. Anthropic builds some of its own features this way. The Latent Space post lists six built-ins, including diff, agents-md, sec-default and you-should-know, the last of which is off by default.

Alternatives, from the sources:

We did not fetch Cursor's or OpenAI's own pages, so treat those two descriptions as one writer's framing.

Who it's for

Pick this up if you already live in Claude Code, you can name a specific friction, and a settings hook can't express the fix because you need a preview, a button or state that persists across the session. Team leads also fit. azukiazusa explains that mods an administrator places with prependPlugins sit on the outside of the chain and can audit every event, including denied ones.

Skip it if your rule just has to always hold. StationX advises using the lightest tool first and quotes Kevin Riedl of wavect: "Mods do not invent the ability to stop an action." Skip it, too, if you mostly run headless. CellCog's reading of the docs says the interface a mod draws appears only in the terminal and the Desktop app's Code tab. And skip it if you aren't willing to read code before you install it.

Before and after

Before, with a settings hook:

  1. Write a script that matches --force or rm -rf and register it in settings.
  2. Claude proposes the command and the script exits with a deny.
  3. You see a refusal with no view of what would have changed.
  4. To override it, you edit the script or run the command yourself.

After, with a guard mod like blast-radius:

  1. Claude proposes rm -rf build.
  2. The mod's tool.call hook answers instead of calling next, and the command is held.
  3. The mod shows what the command would change, with buttons to proceed or cancel (docs).
  4. Proceed passes the call down the chain. Cancel returns a deny, and any outer mod still sees the result.

The same pattern extends past guards. Latent Space describes Anthropic's You Should Know side agent flagging that the file being edited, and about 45 others, already had uncommitted work, with a suggestion to commit or stash first.

Try it

Check your version. Anthropic's guide lists v2.1.287 or later for the terminal, and the docs say the Desktop app supports mods from v2.1.286:

claude --version # 2.1.287 or later

Next, get the sample. Per the docs, Anthropic shares sample mods in the claude-code/mods directory of the claude-code-playground repository, "as they are, without support." You can load one for a session with --plugin-dir. To keep it, add the clone's claude-code/mods directory as a marketplace and install from claude-code-playground-mods. Before loading anything, run claude plugin validate on the plugin's directory. According to Better Stack, it reports the events the mod handles and every mods API call it makes, without executing the code.

You can also skip the code and describe what you want. Anthropic's guide says Claude Code has a built-in skill for writing mods and offers hot reloading for the session. Better Stack says these session mods land in ~/.claude/dev-mods/ and are cleaned up after cleanupPeriodDays, so copy the folder out if you want to keep one. None of the sources give a separate price for mods. Any mod that calls a model spends your usage.

Where it breaks

Mods are not sandboxed. The docs say a loaded mod can read and write files anywhere your account can, read environment variables and API keys, see every prompt, rewrite tool calls, approve a call before you're asked, and spend your usage. CellCog reads this as meaning a mod can approve a call that an ask rule would have prompted for. The one thing a mod can't restyle is the permission prompt. Dash Security analyzed the preview at v2.1.277. It found that $.settings.read() returns settings unfiltered, env included, that $.mcp.call invokes connected MCP servers without a permission prompt, and that a mod in ~/.claude/skills loads with no install step.

Other weak points:

Still open:

Sources