Claude Code Mod Mode First Steps — Safety Guards and Custom UI in 80 Lines

·

Key Takeaways

  • A mod is a JS/TS extension loaded once and resident in the Claude Code session. Unlike shell-based hooks, it maintains state, observes and mediates events, and can render custom UI.
  • It hooks into multi-stage events such as prompt submission, tool calls, turn and session start/end, and UI rendering, supporting three modes: pass-through (observe), modify input (intervene), or handle directly (consume).
  • Claude Code’s AGENTS.md support and /diff panel are themselves implemented as mods, confirming that mods are not an add-on but the foundation of core UI components.

A mod is not a mere theme. It is a “second operating-system layer” inside Claude Code that lives in the session, observes and mediates events, and can redraw the UI. The key insight is that you can describe the desired behavior in natural language and keep state in $.state, and immediately attach safety guards, cost displays, and workflow checkpoints.

Table of Contents

Once you start using Claude Code seriously, the first frustration you hit is, “Can’t I just tweak this screen to match my workflow?” You’re used to wiring a shell script into ~/.claude/hooks.json as a safety guard, but that approach forces you to spawn an external process every time, gives you no way to keep state, and lets you touch nothing about the UI. That gap is exactly where Claude Code mod mode steps in. It has been available by default since version 2.1.287 with no extra setup, and the fact that AGENTS.md and the /diff panel are already implemented as mods speaks volumes about its standing.

Concept Overview: Which Events Can You Intercept, and How Far?

A mod is a JS/TS extension loaded once and resident for the life of a session. You can hook into multi-stage events such as prompt submission, tool calls, turn and session start/end, and UI rendering, and choose whether to let the event pass through (observe), modify the input before forwarding it (intervene), or handle it directly and end the flow (consume). It follows the same manifest and hook module structure as a regular plugin, but the decisive difference unique to mod mode is that it runs inside an embedded runtime (such as V8) rather than a shell. That’s what makes it possible to draw a graph of context usage, visualize the blast radius right before a dangerous command runs, and step through changed files turn by turn — all from a small module you write yourself.

Example 1: Token Weather — A Context Forecast in 80 Lines

Token Weather, at roughly 80 lines, shows just how compact a mod can be. The module accumulates each turn’s token usage in $.state and maps the ratio against the context limit to a weather icon — clear below 50%, cloudy near 70%, showers from 85%, and storm at 95% or higher. Above the prompt input, it shows a mini chart (the last 12 turns) along with the delta from the previous turn, and surfaces a hint like “Recommend running /compact” when a threshold is crossed. If you fail to preserve state, the chart resets to 0 on every hot reload. The key to avoiding that trap is to store the value in $.state, not in a module-level variable. This was the single point I missed most often when writing my first mod.

Example 2: Blast Radius — Visualizing Impact Right Before a Dangerous Command

Commands like rm -rf, git reset –hard, git push –force, and prisma migrate deploy are hard to undo once they’ve run. Blast Radius hooks in just before a tool call, identifies risky patterns, and compiles the impact at that moment — git status, the number of changed files, the push target branch — into a side panel or a modal above the prompt. A responsive layout inside the module automatically switches to a top banner when the terminal width gets narrow. The tool does not execute until the approval button is pressed.

That said, aliases and internal company wrapper scripts will never be fully caught by string matching. For operations that truly need to be blocked, it’s safer to register them separately under permissions.allow/deny in settings.json. The recommended split is: Blast Radius is responsible for “raising the warning,” while the permission layer handles the actual block.

Example 3: Replay Theater — Stepping Through a Turn’s Changes

When Edit/Write is called multiple times within a single turn, it’s hard to keep in your head which file changed, in what order, and how. Replay Theater intercepts Edit/Write events, stacks filename and before/after snapshots into an array, and opens a stepwise diff panel on the side when you press r or /replay. Unlike Blast Radius, it does not block execution; it focuses on observation and review. In teams without a strong code-review culture, using it as a self-review step just before opening a PR is highly effective.

The most commonly missed pitfall in practice is that file_path and old_content in the event object can be empty. An Edit that follows a Read is not guaranteed to have old_content, so you need defensive code — for example, showing a placeholder instead of passing an empty string straight into a diff viewer.

Build Your Own: A Workflow That Starts with a Single Line of Natural Language

The process of creating a mod is surprisingly ordinary. Run claude –plugin-dir ./my-first-mod in an empty folder to launch a session, then describe in natural language — “show a graph of context usage above the prompt” — and Claude Code will write the manifest and hook module for you. The moment you save the file, the plugin hot-reloads and the change is reflected immediately without restarting the session. If the UI doesn’t appear, run claude –debug and follow the logs to pinpoint the event stage where it failed.

When you’re done, run claude plugin validate to statically check the manifest contract and types, and claude plugin test to confirm behavior in the actual runtime. Because API signatures change slightly with each release, if type declarations for that version are generated under .claude-plugin/types/, import from there to secure type safety.

State Management and Debugging: $.state Is the Answer

Any data that needs to survive a hot reload must live in $.state. If you declare an array as a top-level module variable, it becomes a candidate for garbage collection at reload time and is reset. $.state, by contrast, is an area the Claude Code runtime explicitly preserves. Token totals, recent change history, and user-pinned thresholds should all be funneled there. If the UI doesn’t render at all, check in this order: 1) a typo in the event registration key in the manifest, 2) a require failure caused by missing type definitions, and 3) a missing module export. These three account for the vast majority of debugging time in practice.

Distribution and Security: Publisher Trust Is the Control Mechanism

A mod created inside a session is loaded only into that session by default. To keep using it, copy the folder under ~/.claude/plugins/, or place a marketplace file alongside it on GitHub and register it, then run /reload-plugins. It follows the same workflow as a regular plugin, so it can be submitted to the Claude directory as well.

This is where security deserves attention. A mod runs on the user’s machine with the same privileges as the Claude Code binary itself. That property — user-supplied code executing directly on the local machine — is a recurring concern in on-device AI workflows as well, so the same standard should be applied when assessing a mod’s permission model. As the Cantina apex-flash-1 case shows, paths by which untrusted code obtains arbitrary privileges are hard to shut down with a single static analysis pass. Publisher trust, source review, and least-privilege principles must always be applied together.

Wrapping Up: Wrap the One Behavior That Annoyed You Today

Calling mod mode a “second operating-system layer” is not an exaggeration. Describing the desired behavior in natural language and putting state in $.state is enough to attach safety guards, cost displays, and workflow checkpoints on the spot. Ideas like cost/limit displays, team-rule injection, K8s context checks, and pre-apply Terraform review are all realistic within a weekend of writing your first mod. Don’t try to design a giant plugin from day one. The fastest path is to take the one behavior that annoyed you today and wrap it in an 80-line mod. More examples and demo videos are available in the original guide.

Try It Right Now

  • Create an empty folder with mkdir my-first-mod && cd my-first-mod, launch a session with claude –plugin-dir ., and ask in one line: “draw a graph of context usage above the prompt.” Verify that the manifest and hook module are auto-generated.
  • In the generated hook module, change the running counter to be stored in $.state rather than a module variable, and after saving, verify that the chart does not reset to 0 on hot reload.
  • If you need a dangerous-command guard, add a PreToolUse hook in the hooks module that matches patterns like “rm -rf,” “git push –force,” and “prisma migrate deploy,” and have the result pop up as a modal — about 30 lines. For hard blocking, register the same patterns separately under permissions.deny in settings.json.
  • Run claude plugin validate ./my-first-mod to statically check the manifest and type contract, and claude plugin test ./my-first-mod to write regression tests that confirm the event flow behaves as intended in the real runtime.
  • When you’re done, copy the module to ~/.claude/plugins/ or register it together with a GitHub marketplace file, then confirm permanent application with /reload-plugins.

Frequently Asked Questions

How should I split work between shell scripts registered in the existing hooks.json and mods?

If you only need stateless, one-line guards (e.g., blocking dangerous commands, writing logs), the shell hooks in hooks.json are light and sufficient. If you need to show accumulated context while the session is alive, mediate tool calls, or draw UI, move that work into a mod. Permission denial is ultimately the most reliable layer in settings.json’s permissions, so the actual block should live in the permission rules rather than in shell hooks or mods — that is the recommended split.

API changes every release make me hesitate to adopt a new mod. What’s the stable path forward?

Use the type declarations generated under .claude-plugin/types/ when you load against that version, and wrap event names in constants. When a signature changes, the compiler will catch it immediately. Scenario-ize the core event flows with plugin test so you can quickly tell whether a regression has occurred on upgrade day.

What’s a realistic flow for rolling out a standard mod across the whole team?

Keep a single repository on internal GitHub that includes the marketplace file, and require all modules to go through code review. New hires get the same set with a single registration command, and the fact that publisher trust is recorded as a code-review history is the key control that offsets the mod’s powerful permissions.

Source Reference

This article was written with reference to the following original: geeknews — Getting Started with Claude Code Mod

Leave a Reply

Your email address will not be published. Required fields are marked *