Claude Code mods: in-session hooks that can rewrite tool calls and draw UI

Claude Code 2.1.287 adds mods, JS/TS hooks in plugins that can guard commands and draw UI, for devs willing to maintain their own harness code.

Picture a platform engineer at a 30-person SaaS shop who runs Claude Code in a repo that also holds Terraform configs and a kubectl context pointed at production. Today the guardrails are a deny list in settings plus a settings hook. The hook is a shell script that receives each tool call as JSON on stdin, greps for terraform apply or rm -rf, and refuses. Mostly it works. But the script starts fresh on every event, so it remembers nothing from earlier in the session. It can't show what a command would touch before it runs. And when the engineer wants a better way to read a turn's worth of edits, there's nowhere to draw one.

Anthropic's Claude Code mods are aimed at that gap. Per the getting-started guide published October 1, 2026, a mod is a JavaScript or TypeScript module, shipped inside a plugin, that loads once into your session, sees every event and can observe it, rewrite it or answer it, including the UI. One of Anthropic's reference mods, Blast Radius, is a guard for the commands that make you nervous. The catch is in the same guide: the API can change between releases. Treat a mod as code you maintain.

What it is

According to Anthropic's guide, mods need Claude Code 2.1.287 or later and are on by default. Under the hood, mods are hooks, and they ship inside plugins. A mod is a plugin with a .claude-plugin/plugin.json manifest and a hooks/hooks.json that names exactly one module. That module exports register(on, options), and every hook has the same shape:

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. Each capability maps to a piece of the lede's problem:

Events cover tool calls, the submitted prompt, turn start and finish, session start and end, slash commands and rendering. Anthropic says some of Claude Code's own features are built as mods, including AGENTS.md support and the /diff pane. Their source, with tests, sits under mods/ in the anthropics/claude-code repository. RuntimeWire reports that users can disable /diff or substitute their own version.

The guide builds Token Weather, a context-window meter of about 80 lines, and tours two larger mods. AlphaSignal's summary describes them. Blast Radius intercepts Bash calls, classifies commands such as rm -rf and git reset --hard, runs dry-run checks through $.process.run, and opens a side pane with Proceed and Cancel. Replay Theater records Edit and Write calls and adds a /replay command that steps through the diffs. Anthropic engineer @trq212 says he uses a community mod called next-steps, that mods can spin off forked agents (for example, a custom memory classifier every turn), and that he is "still working on making plan mode into a mod."

Alternatives, from what our sources support:

We found no source to compare Cursor's extension and rules model.

Who it's for

Pick this up if you work in Claude Code in the terminal or the desktop app's Code tab and already have a settings hook or permission rule you wish could do more: remember things, show a confirmation pane, or render a custom review. Team leads should look too. AlphaSignal lists uses like a prompt.submit handler that adds team conventions, or a guard that asks for confirmation before kubectl targets production. The Claude Help Center shows how Team and Enterprise owners can distribute plugins through organization marketplaces, either by ZIP upload or by syncing a private GitHub repository.

Skip it in these cases:

Before and after

Before (settings hook):

  1. Write a shell script, then register it as a hook in settings.
  2. On each tool call, Claude Code starts the script and passes JSON over stdin.
  3. The script pattern-matches the command and either allows it or refuses it.
  4. Any history has to go to a file the script re-reads, and there's no on-screen preview.
  5. Reviewing edits means scrolling the transcript or switching to git.

After (mod):

  1. Describe the guard to Claude, or write a tool.call hook matched to Bash.
  2. The module loads once and keeps history in $.state.
  3. On a risky command, run a dry run through $.process.run, as Blast Radius does, and show a Proceed/Cancel pane.
  4. Answer with a deny, rewrite the command, or pass it on.
  5. Add a /replay-style command that steps through the turn's edits in a docked pane.
  6. Check the mod with claude plugin validate and test it with claude plugin test, which AlphaSignal says runs *.test.ts files against the Claude Code runtime.

Try it

Check your version first. The guide gives this command:

claude --version # 2.1.287 or later

The guide's shortest path is to start claude and describe the mod you want. Claude asks once whether to turn on hot reloading for the session, and then reloads each tweak in place. That session-only mod's folder is cleaned up later, so to keep it, copy the folder out and install it like any plugin. To build one by hand, follow the guide's layout and run claude --plugin-dir ./token-weather. The folder is watched, so every save reloads the module.

To try an existing community mod, @trq212's post gives:

claude plugin marketplace add anthropics/claude-plugins-community  

claude plugin install next-steps@claude-community

Before installing someone else's mod, Nerd's Chalk suggests running claude plugin validate on its directory. It shows the events the mod handles and the operations it requests without running it. None of our sources mention a separate price for mods. Nerd's Chalk notes that a mod can make model calls charged to your plan or API key.

Where it breaks

Sources