Write Your First Claude Code Mod: From Blast Radius to Your Own Agent Guardrail

Decide first: what should your first mod be

The mod system just launched and people are already running Doom inside it and building fancy dashboards. But hear me out: your first mod shouldn't be a toy — it should be a guardrail.

The reason is simple. The more powerful mods are, the sooner you need to develop a feel for controlling them. A mod that intercepts dangerous commands will save you from countless slips over the coming months; a Doom port earns you nothing but a social media post. Blast Radius is the most important of the three official examples precisely because it answers a real question: as agents grow more autonomous, who steps on the brakes?

So this guide has one concrete goal: build a "Blast Radius lite" — intercepting rm -rf, git reset --hard, and git push --force, and showing you which files a command would touch before it runs. Finish this one and you'll own the full feel of mod development.

Step 1: Understand the event model (5 minutes)

A mod's core is an event-hook model. A mod can attach at three points: before an event, after it, or instead of the event itself. Hookable events include tool calls, permission requests, prompt submissions, and UI rendering.

Our guardrail mod needs exactly one hook: intercepting at before the "tool call" event. The logic: when Claude Code is about to run a shell command, the mod first grabs the command text and pattern-matches it — on a dangerous pattern it pauses execution, pops a side panel showing which files the command would touch, and only proceeds after your confirmation.

When several mods hook the same event they form a chain in load order — first loaded sees the event first. So remember one iron rule: security mods must always load first. That's exactly what the enterprise sec-default built-in mod does — it loads first, specifically to prevent later mods from overriding deny rules.

Step 2: Have Claude Code write it for you (10 minutes)

This is the most interesting part of the whole flow: Anthropic officially says you can ask Claude Code to write a mod for you, then hot-reload it into the session. In practice, your prompt needs to be specific about three things:

First, what to intercept: "Write a mod that hooks before tool-call events. If a shell command matches rm -rf, git reset --hard, or git push --force, block execution and pop a confirmation panel." Second, what the panel shows: "Use git ls-files and simple path expansion to list the files the command might affect, flagging anything outside version control." Third, the boundaries: "Only intercept and display — never auto-approve; the code must not phone home or read files outside my home directory."

After Claude generates it, don't install yet. Ask it to explain in its own words what each part does — the fastest way to check whether it wrote something you didn't ask for.

Step 3: Install, hot-reload, verify (5 minutes)

Mods ship as plugins and install with /plugin, in both the CLI and the desktop app. No restart needed — mods hot-reload, so code changes take effect immediately. To verify, deliberately have Claude run a harmless dangerous command, like rm -rf ./tmp-test in a scratch directory, and confirm the intercept panel appears, the file list is accurate, and the command only runs after you confirm.

The verification checklist has three items: does the intercept trigger, is the panel accurate, does execution behave normally after approval. Pass all three and the mod is ready for long-term duty.

Step 4: The security self-check (run before installing any mod)

Because mods run with the same machine access as Claude Code, do these four things before installing a third-party mod: read the code — a mod is a few dozen lines of TypeScript; if you can't read it, don't install it; check network behavior — search for fetch, axios, or URLs assembled in child_process; a guardrail mod has no business phoning home; check the permission surface — which events does it hook? A UI-beautification mod shouldn't touch permission-request events; pin versions — note the version when installing from a marketplace, and read the diff before upgrading.

The last one is for teams: put shared guardrail mods in an internal plugin marketplace and distribute them from the admin side instead of letting everyone install their own. Trust boundaries are easier to manage when centralized.

After the first one: three worth building next

Once you have the feel, continue in this order: a secret-redaction mod — after tool-output events, automatically mask anything shaped like an API key or token before display; a commit-message lint mod — check message format before git commit and reject anything violating team conventions; a context-budget mod — following Token Weather's idea, proactively nudge you to start a fresh session when context passes 70%. All three are the "quietly protects you every day" type.

One-line summary: the real value of the mod system isn't making the agent flashier — it's letting you, for the first time, write "things I don't want it to do" as code and pin them into the agent's main loop. Guardrails first, toys later — don't reverse the order.