💡 Claude Code Mods: TypeScript Hooks That Let You Rewrite the Agent From the Inside

Claude Code 2.1.287 (released October 1) ships a new plugin primitive called Mods. A mod is a TypeScript or JavaScript file whose exported functions Claude Code calls when events happen — a prompt is submitted, a tool call starts, or a UI element is drawn. The key insight is that the handler sits in the middle of the event pipeline: it can watch, modify, or completely replace the behaviour before Claude Code's own logic runs.

The three-argument hook signature

Every hook receives the same three arguments:

• $ — the Mods API: namespaced methods to reach outside the hook, including $.ui.write(), $.command.register(), and $.tool.override().
• e — the event: plain data describing what happened, such as the tool call name and arguments, or the submitted prompt text.
• next — a function that passes the (optionally modified) event on to the remaining mods and then to Claude Code itself, returning the result.

A minimal working example

// prepend-date-mod/index.ts
export function register(on) {
  on("prompt:submit", async ($, e, next) => {
    // Prepend an ISO date stamp to every prompt
    e.text = `[${new Date().toISOString().slice(0, 10)}] ${e.text}`;
    return next($, e);
  });
}

Install it with /plugin install ./prepend-date-mod. When Claude Code loads a mod from a directory, it writes TypeScript declaration files (ending in .d.ts) into .claude-plugin/types/ inside the mod's directory. These describe every event, API method, and UI element available in the exact Claude Code version you're running — enabling editor autocomplete and type checking without any manual setup.

💡 "You Should Know": The Built-in Side Agent That Watches What the Main Agent Misses

2.1.287 ships a first-party built-in mod called You Should Know. It runs as a background side agent that passively monitors the same tool calls and messages as your main Claude Code session, then surfaces things you — or the primary agent — may have overlooked: a security implication buried in an API response, a conflicting configuration in a file being edited, an edge case in a function being refactored.

Enabling it

/plugin enable cc-plugin-you-should-know@builtin

The side agent outputs observations inline, indented and prefixed with a distinct marker so they don't interrupt the main agent's flow. It does not take actions — it only writes to the session stream.

Constraints to know before enabling

• First-party sessions only: the plugin does not activate in third-party API sessions or when custom system prompts are set. It requires telemetry to be on so Anthropic can improve its signal-to-noise ratio over time.
• Token cost: the side agent receives the full context window. On long sessions, this meaningfully increases token usage. If you are running Claude Code on a tight per-session budget, check your usage before leaving it on permanently.
• Noise calibration: the initial release may surface more observations than are actionable. The plan is to improve threshold tuning via the telemetry data collected. You can disable it session-by-session with /plugin disable cc-plugin-you-should-know@builtin.

💡 The Mods Security Model: Full Host Access, No Sandbox — What That Means in Practice

The official Mods documentation states it plainly: "Mods run with the same access to your machine as Claude Code itself. They are not sandboxed." A mod can read and write files, spawn child processes, make outbound network requests, and access environment variables — including API keys. This is by design, not oversight. Deep extensibility requires real access to the host environment.

What to check before installing a mod

• Read the source: mods are TypeScript files — the source is human-readable. Before installing anything from outside your organisation, spend two minutes reading the hook handlers. Watch for: outbound fetch() calls to unknown endpoints, reads of ~/.ssh/ or ~/.config/, and use of $.tool.override() to silently intercept tool calls.
• Verify the plugin package: install from a pinned version rather than @latest to prevent a compromised registry update from silently replacing a mod you reviewed.
• Org admin controls: enterprise admins can configure an organisation-level allowlist via the settings at code.claude.com/docs/en/plugins/mods/admin. This restricts which mod packages members can install — the same model as managed browser extensions. If you manage Claude Code for a team, set this up before Mods proliferate.
• Least privilege where possible: if a mod only needs to intercept prompt:submit, it has no reason to subscribe to tool:call events. A mod requesting broad event subscriptions beyond what its stated purpose requires is a red flag.