Claude Code Mods: Write TypeScript Plugins That Rewrite the Agent

Claude Code can now be rewritten from the inside. On October 1, Anthropic shipped Mods — small TypeScript modules that live inside the agent’s execution pipeline, intercept tool calls, redraw the terminal UI, and replace built-in features entirely. This is not prompt engineering. It is code running inside Claude Code itself, with the same machine access the agent has.

To make that concrete: the diff pane you see in Claude Code is now a mod. The agents.md loader is a mod. Telemetry is a mod. Anthropic converted three of its own features on launch day and open-sourced them in the main repository. These are not experimental hooks — they are the new extensibility layer.

Mods vs. Settings Hooks: What Changed

Before Mods, Claude Code had settings hooks: shell scripts that fired when something happened and could allow or block an action. They ran outside the Claude Code process, could not rewrite events, and had no access to the UI.

Mods change all of that. They run inside the session and can:

• Rewrite a tool call’s input before it executes
• Deny a tool call entirely with a custom reason
• Rewrite the system prompt before it sends
• Draw side panes, status bars, and buttons in the terminal UI
• Add /slash-commands that run without a model turn
• Replace a built-in feature with your own implementation

If settings hooks are .gitconfig entries, mods are VS Code extensions. Same agent, entirely different level of control.

The Three-File Structure

A mod ships inside a plugin. The minimum to get one running is three files:

.claude-plugin/
  plugin.json        # name, version, description
hooks/
  hooks.json         # { "modules": ["./register.tsx"] }
  register.tsx       # your mod logic

hooks/register.tsx exports a single function:

export function register(on) {
  on('tool.call', { tool: 'Bash' }, async (event, next) => {
    // intercept, rewrite, or deny — then call next() to continue
    return next(event);
  });
}

The four events that matter: tool.call (any tool the agent invokes), prompt.submit (fires before the prompt sends), prompt.compose (rewrite the system prompt), and ui.render (redraw any UI component). Install with /plugin install path/to/your/plugin in the CLI or desktop app.

Build Your First Useful Mod: Destructive Command Guard

The most practical first mod is a guard that intercepts destructive Bash commands before they execute. The community shipped this within hours of launch, and engineering teams are already adopting it for governance.

// hooks/register.tsx
export function register(on) {
  on('tool.call', { tool: 'Bash' }, async (event, next) => {
    const cmd = event.input.command ?? '';
    const dangerous = /rm\s+-rf|DROP\s+TABLE|git\s+push\s+--force/.test(cmd);

    if (dangerous) {
      return {
        deny: true,
        reason: `Destructive command detected: "${cmd}". Confirm manually.`,
      };
    }

    return next(event);
  });
}

That is 15 lines. It blocks every rm -rf, force push, and DROP TABLE the agent tries to run and surfaces the command with a reason. Start here. One mod that solves a real problem beats ten experimental ones.

Security: Not Sandboxed

Mods run with the same access to your machine as Claude Code itself — no sandboxing. The privileged engine interface ($) exposes file reads, shell commands, and network calls. Researchers at Pluto Security found that $.fs.read is not project-scoped: in testing, a mod could read Claude Code’s OAuth credentials and the full prompt history from history.jsonl.

The rule is simple: only install mods from sources you trust, the same way you’d treat any code you run on your machine. On Team and Enterprise plans, a built-in sec-default mod loads first and prevents installed mods from overriding permission deny rules.

What the Community Already Shipped

Three days after launch: over 40 GitHub repositories, a community catalogue on GitHub, and 50+ MIT-licensed mods with tests. The range is wide — token usage charts, CI status overlays, a “You should know” callout injector for flagging key output details, and a playable Tetris game running in a session pane.

The governance end is more durable. Mods that require confirmation before destructive operations, enforce commit message formats, or surface test failures inline — these are the ones that will stay installed. Browse ExplainX’s curated list of 50 open-source mods to find ones worth adopting now.

Where to Start

Read the official Anthropic announcement for the canonical architecture overview, then work through the getting started guide on claude.dev for a hands-on walkthrough. The three-file structure takes about five minutes to scaffold, and Claude Code can write the mod for you if you describe what you want — which is a somewhat recursive experience worth having.

Pick one workflow pain point — a command you never want the agent to run unsupervised, a UI element that should surface differently, a tool call you want to log — and build the mod for that. The ecosystem is three days old and already moving fast. The engineering teams that figure out their internal mod stack now will have a real productivity edge within months.