On October 1, Anthropic added an extension mechanism called mods to Claude Code. Per the official blog, a mod is a small TypeScript function that hooks into Claude Code's events — it can rewrite prompts, add UI elements, replace built-in features, or add an entirely new feature. Both the CLI and the desktop app support it, and it requires Claude Code 2.1.287 or later.
Distribution runs through the existing plugin system: install from the Claude plugin marketplace, or run /plugin inside a session. To let other people use a mod you wrote, package it as a plugin and submit it to the marketplace.
What mods can touch
Every action inside Claude Code — calling a tool, requesting a permission, drawing a piece of the screen — fires an event, and a mod can run before it, after it, or replace it entirely. The capabilities the official docs list include:
- rewriting the prompt that reaches the model;
- intercepting, rewriting, or retrying tool calls;
- approving or denying permission requests;
- redacting part of a tool's output before Claude ever reads it;
- adding buttons and input fields to the interface.
The developer blog's getting-started tutorial, written by Addy Osmani, goes deeper into how the model-facing side works. Each hook sits on a middleware chain and can be written three ways: call next(e) to pass the event through and inspect the result afterward — that's observing; pass a modified event further down the chain — that's rewriting; or skip next() entirely and return {deny: "reason"} directly — that's answering. The events covered include tool calls, prompt submission, the start and end of a turn, slash commands, and UI rendering.
The tutorial's example is a roughly 80-line mod called Token Weather. It draws a "context weather forecast" above the input box: a weather icon that changes with how much of the context window is used, the current token count and percentage, a mini sparkline of the last 12 turns, and a marker showing how much it rose compared with the previous turn. The UI piece uses the AbovePrompt component.
From hooks to mods
Claude Code already had settings hooks: every event spawned a shell command, and JSON was passed through stdin and stdout. That approach is simple, but it costs a new process every single time, and it has no memory of what happened last time.
Mods load once when a session starts and then stay resident. The tutorial lists three differences this makes: a mod can hold state, render UI that keeps changing, and call Claude Code's own functions, such as opening a panel or registering a command. Token Weather's 12-turn sparkline depends on exactly this kind of persistent state — a shell hook would have had to write its own log to disk to pull off the same trick.
Strung together, Claude Code's extensibility has been built up in layers: first CLAUDE.md and settings hooks, then the /plugin marketplace, and more recently AGENTS.md support, which itself shipped as a built-in plugin. Mods turn a hook from "a bolted-on script" into "code that runs inside the process," and that widens what can be changed by a lot.
The security boundary
A wider scope means wider risk. The official blog is blunt about it:
Mods run with the same access to your machine as Claude Code itself. They aren't sandboxed, and you should only install mods from sources you trust.
The tutorial describes the runtime a different way: a mod module runs in its own isolated environment, with no DOM and no Node, and every outward-facing action has to go through the $ interface. Read both statements together and what's actually isolated is the runtime, not the permissions. A mod that gets hold of a permission event can click "approve" on the user's behalf.
Team and Enterprise plans, and any machine with managed settings installed, load a built-in mod called sec-default first, which blocks high-risk moves from user-installed mods, such as overriding a permission denial; admins can also restrict which plugin marketplaces are allowed in the enterprise console. Individual accounts get no such backstop by default. For teams in mainland China, where the account and network barriers to using Claude Code are already high, mods look for now more like an extra customization tool for teams that are already using it; how fast a third-party mod ecosystem can grow will depend on how loosely the marketplace review is set.
Sources: Anthropic's official Claude blog, the Claude developer blog's getting-started tutorial, CocoLoop; the official tutorial for version requirements, event types, and example code line count.