3 Claude Code Mods That Change How the Agent Behaves

You are not only adding features to Claude Code anymore. With mods, you can change how Claude Code itself behaves — tool calls, prompts, turns, and the terminal UI (Anthropic announcement).

Anthropic's getting-started guide (published Oct 1, 2026) does not pick three random demos. It ships three sample mods that each solve a different job: context awareness, risky-command control, and post-turn review (Getting started with Claude Code mods). This post walks through those three — Token Weather, Blast Radius, and Replay Theater — and what each one is for.

Key Takeaways

• Mods are TypeScript/JavaScript plugins that hook Claude Code events and can draw their own UI. They require Claude Code v2.1.287+ and are on by default (mods guide).
• Token Weather shows a live "forecast" of how full the context window is above the prompt — Clear → Storm → Compact soon.
• Blast Radius holds risky Bash (rm -rf, force push, git reset --hard, migrations, …), previews impact, then Proceed / Cancel.
• Replay Theater records Edit/Write in a turn and lets you step through diffs with /replay or r.
• Mods are not MCP tools or simple slash commands: they can observe, rewrite, or answer events in the hook chain.

What Claude Code Mods Actually Are

Answer first: a mod is a Claude Code plugin whose behavior lives in a JS/TS module. hooks/hooks.json points at one module; that module exports register(on, options) and attaches hooks to events such as tool.call, turn.complete, ui.render, and command.run.

Hooks form a middleware chain. Your hook runs, next(e) passes the event onward, and Claude Code does its default work at the end. A hook can:

That is the real difference from MCP servers (extra tools for the model) or statusline scripts (display-only). Mods sit inside the session, keep state, open panes, and can block or rewrite what would have happened.

Anthropic also notes that some built-in Claude Code features — including AGENTS.md support and the /diff pane — are themselves implemented as mods, with source under mods/ in the public anthropics/claude-code repository (mods guide).

Prerequisites

claude --version   # need 2.1.287 or later

Mods are enabled by default. The API can still change between releases; when Claude Code loads a mod it writes type declarations into the mod's .claude-plugin/types/ folder — those types match your build (mods guide).

Treat third-party mods like any package that runs on your machine: read the repo, install only from sources you trust.

The Three Sample Mods at a Glance

1. Token Weather — See Context Before It Surprises You

Value: you no longer have to guess how full the context window is.

Token Weather reads $.session.usage() after each turn and draws one line above the prompt: weather icon + word, percent used, tokens out of the window, a short sparkline of recent turns, and how much the last turn added (mods guide, mods showcase).

Conceptual readout:

Context Window

██████████████░░░░░░ 72%

Used: 72%
Remaining: 28%

In a real session the band is a single status line (for example ☂ Showers 67% of context 134.4k / 200k plus a sparkline). On large repos or multi-hour coding sessions, that line is the difference between "Claude got confused" and "we were already at Storm."

The reference implementation is roughly 80 lines. Anthropic's guide also shows a shortcut: paste a natural-language prompt into Claude Code and let it scaffold token-weather with hot reload in the same session (mods guide).

2. Blast Radius — Intercept Dangerous Shell Before It Runs

Value: instead of giving Claude blanket trust, add a guard that interrupts critical shell.

When Claude calls Bash with patterns such as rm -rf, git reset --hard, git clean, a force push, or a database migration, Blast Radius holds the call, estimates what would change (via dry-run style checks like git clean -n, git status --porcelain), and opens a pane with Proceed and Cancel (mods guide).

Imagine Claude wanting:

rm -rf node_modules

or:

git push --force

What you get is closer to:

⚠ Risky command detected

git push --force

Potential impact:
• Remote branch will be rewritten
• Existing commits may be lost

[ Cancel ]   [ Proceed ]

In Anthropic's recording, Cancel returns a refusal to Claude with a reason; Proceed runs the original command. Hotkeys: 1 = Proceed, 2 = Cancel.

Important honesty from the official guide: Blast Radius is a safety net, not a permission system. It classifies command text, so aliases, $(…), or scripts that call rm can slip past. Use Claude Code permission rules when you need a hard block (mods guide).

Under the hood this is the answer move on tool.call for Bash: measure impact, wait for a UI decision, then either next(e) or return { deny: "…" }.

3. Replay Theater — Step Through Claude's Last Edits

Value: "What did Claude just do?" becomes a step-through, not one giant diff.

Replay Theater records every Edit and Write in a turn (file path + before/after text). When the turn ends, a hint appears above the prompt. Press r or run /replay to walk edits one diff at a time — numbered steps, Prev / Next / Close (mods guide, mods showcase).

If Claude touched eight files in one turn:

/replay

Step 1 → app/api/auth.ts
Step 2 → lib/auth.ts
Step 3 → middleware.ts
Step 4 → app/login/page.tsx
…
[ ← Previous ]  [ Next → ]

It never blocks or rewrites edits — pure observe. That makes it ideal for demos, teaching, and learning in what order the agent solved a problem.

How the Three Fit Together

• Token Weather answers: How much context is left?
• Blast Radius answers: Should this shell command run?
• Replay Theater answers: What files changed, and in what order?

Together they show the mods thesis: you are not only bolting on MCP tools — you are reshaping Claude Code's loop and UI. If your stack already leans on MCP for browser, docs, and research, keep that layer (5 Claude Code MCPs); mods sit underneath and change how the agent acts, not only what it can call.

Try or Build a Mod Yourself

Local plugin dir (fastest for learning)

claude --plugin-dir ./token-weather

Edits hot-reload while the session stays open.

Share via marketplace (three commands)

Mods install like any other plugin. From Anthropic's guide:

/plugin marketplace add your-org/my-mods
/plugin install token-weather@my-mods
/reload-plugins

Or from the CLI with a local marketplace folder:

claude plugin marketplace add ./my-mods
claude plugin install token-weather@my-mods --scope user

Validate and test with:

claude plugin validate ./token-weather
claude plugin test ./token-weather

(mods guide)

Shortcut: describe the mod to Claude

You do not have to memorize the API first. Anthropic's Token Weather shortcut is a paste-ready prompt that asks Claude to create the mod and enable hot reload. Change the "what it should show" lines and it becomes your mod (mods guide).

FAQ

Do mods replace MCP?

No. MCP adds tools the model can call. Mods hook the Claude Code runtime (tools, turns, UI). Use both: MCP for capabilities, mods for behavior and guardrails.

Are sample mods built into every install?

Anthropic documents Token Weather, Blast Radius, and Replay Theater as the teaching samples on claude.dev/mods and in the getting-started guide. Built-in product features that are also mods (for example /diff, AGENTS.md) live under mods/ in anthropics/claude-code. Treat community marketplaces separately and verify before install.

Is Blast Radius enough to run Claude unsupervised?

No. Pair it with permission rules and human review for production or destructive work. The official guide is explicit that classification by command string is incomplete.

Which Claude Code version do I need?

2.1.287 or later (mods guide).

What to Do Next

1. Upgrade to Claude Code ≥ 2.1.287.
2. Run Token Weather first — lowest risk, immediate feedback in long sessions.
3. Add Blast Radius before you let Claude loose on cleanup or git history.
4. Use /replay after multi-file turns until you trust the agent's edit order.
5. When you have a question the samples do not answer ("cost meter?", "block terraform apply?"), describe that mod to Claude and keep the folder as a plugin.

Mods turn Claude Code from a fixed agent into something you can reshape. Start with Anthropic's three samples, then build the fourth for your workflow.