Claude Code Mods, Explained: I Built One That Watches My Own Agent

A mod is a small plugin that hooks into Claude Code's own agent loop. Not a wrapper around it, not a separate process watching logs. It registers handlers for the events the engine already raises as it works: tool.call fires every time Claude runs a tool, prompt.submit when you hit enter, turn.complete when a turn wraps up. A handler sees the event, can act on it, and calls next() to let everything beneath it keep running.

From there a mod can draw things: a line in the status bar ($.ui.status), a toast ($.ui.toast), a whole pane or a band above the prompt. It can also just watch and stay quiet, which is the shape both of mine take. Neither one blocks anything. They narrate.

Mods hot-reload while you're building one: save the file, it reloads at the end of the turn, and claude plugin validate / claude plugin test check the manifest and hooks against the real engine before you ship anything. That tooling is a decent signal that this isn't a weekend hack feature, but I'll say the honest thing up front: I don't have visibility into Anthropic's roadmap, and I'm not going to promise you this API is permanent. What I can tell you is it's validated, tested, and typed today, which is more than a lot of "experimental" features ship with.

This is the one I'd actually recommend installing. It watches Bash, Write, and Edit calls and flags two things: shell commands that read as hard to undo, and writes to paths that shouldn't be touched without someone noticing.

const RISKY_BASH: RegExp[] = [
  /(^|\s)sudo(\s|$)/,
  /\brm\s+-[a-z]*r[a-z]*f[a-z]*\b/i,
  /curl[^\n|]*\|\s*(sh|bash)\b/,
  /chmod\s+777/,
  /git\s+push\s+--force(?!-with-lease)/,
]
 
const PROTECTED_PATH = /(^|\/)(\.env(\.[^/]*)?$|\.ssh\/|id_rsa|credentials\.json|\.pem)$/

When a call matches, the status line's tally ticks up and a toast fires with exactly what got flagged. That's it: no { deny }, no blocking, no asking permission. This is OWASP LLM08, excessive agency, made visible instead of enforced: the goal isn't to stop the agent, it's to make sure a human notices what it just did, in real time, instead of finding out three commits later.

I went back and forth on whether it should actually block the risky stuff. Decided against it, on purpose: a flagging tool that's wrong once in a while is annoying. A blocking tool that's wrong once in a while is the thing you disable entirely, and then it protects you from nothing. Heuristics stay narrow and visible instead of clever and silent. Tune the regex for your own repo if these don't fit.

Here's what it looks like running against a handful of calls:

No security angle, no excuse, just a motorcycle-themed activity gauge for the status line. It counts tool calls in the current turn and revs through four stages:

const STAGES = [
  { max: 2, label: '🏍️ idle' },
  { max: 6, label: '🏍️💨 cruising' },
  { max: 12, label: '🏍️🔥 revving' },
  { max: Infinity, label: '🏍️🔥💨 full throttle' },
]

Hit full throttle (13+ calls in one turn) and it drops a toast about wearing a helmet. That's the whole mod. I built it mostly to prove the "fun" side of this isn't harder than the "useful" side: same three files, same on('tool.call', ...) shape, just a sillier payload.

Both mods, plus their tests, live in one small repo set up as a plugin marketplace. Install either with one line at the prompt of a terminal session:

/plugin install agent-watch --marketplace hereshecodes/claude-mods
/plugin install throttle --marketplace hereshecodes/claude-mods

That's the whole install. No build step, no config beyond the prompt that shows up asking you to confirm the marketplace. The source, including the test files, is at github.com/hereshecodes/claude-mods if you want to read the hooks before you trust them with your terminal, which, honestly, you should.