Claude Code mods: small TypeScript functions that change how Claude Code behaves

On October 1, 2026, Anthropic introduced mods for Claude Code. A mod is a small TypeScript function that customizes how Claude Code behaves. Anthropic's description: a mod can "rewrite a prompt, add new UI, replace a built-in feature, or add entirely new functionality." Mods work in the Claude Code CLI and the desktop app. They first appeared in Claude Code version 2.1.287.

What a mod can do

Claude Code emits events as it works: a prompt is about to be sent, a tool is about to run, a permission is being requested, output came back from a tool. A mod subscribes to those events and returns a decision. Anthropic lists four things a single mod can do:

• Rewrite a prompt before it reaches the model, for example to add your team's standing context.
• Block, rewrite, or retry a tool call. A mod can stop a shell command that touches a production path, or change its arguments.
• Approve or deny a permission request on the user's behalf, using rules you write instead of a prompt every time.
• Redact secrets from tool output before the model, or the transcript, sees them.

Beyond event handling, mods can add interface. Version 2.1.288 added $.ui.selection(), which gives a mod the text the user selected and the transcript rows it came from, so a mod can act on "this part" of a conversation.

How mods are packaged and loaded

Mods ship inside plugins. That means they follow the plugin controls you already have. People install them from the Claude directory or with the /plugin command in the CLI, and an organization that restricts plugins restricts mods the same way. There is no separate distribution channel to govern.

Two practical details from the announcement:

• Hot reload. Edit a mod and Claude Code picks up the change without a restart, so you can test against a live session.
• You can ask Claude Code to write the mod. Describe the behavior you want ("block any rm -rf outside the repo") and let it generate the function, then read it before you keep it.

When several mods subscribe to the same event, they run in load order. In Anthropic's words, the first mod to load sees the event first and the result last. If two mods both edit a prompt, the second sees the first one's edit. If one denies a tool call, later mods never need to approve it. Order matters, so keep security mods first in the load list.

Mods and hooks

Claude Code already had hooks: shell commands that run at fixed points. Hooks are a good fit for a single, scriptable check. A mod is written in TypeScript, can hold state across events in a session, can change interface, and can handle several event types in one place. If you have a folder of hook scripts that each re-implement the same secret-matching pattern, a mod consolidates them.

Hooks remain the simpler choice for a one-line check. Reach for a mod when the logic needs more than a script exit code.

Built-in mods

Claude Code ships with a few. Two are named in the changelog and announcement:

• sec-default, for Team and Enterprise users, applies security restrictions out of the box.
• "You should know" watches a session and surfaces things worth your attention while it runs.

Treat the built-ins as examples of the pattern before you write your own.

What an admin should decide

Because mods can approve permissions and rewrite tool calls, they sit in your security boundary. Before a team installs them freely:

1. Decide who may install mods. Use the same plugin allowlist you use for skills and connectors.
2. Read every mod from outside your organization. A mod that denies or approves permissions is code that runs with the user's access. Review it like a dependency.
3. Put guardrails in an organization-owned mod, loaded first. A user-installed mod loaded earlier could approve something your policy mod would deny.
4. Log what mods change. If a mod redacts or rewrites, someone debugging an odd result needs to know it happened.

What to build first

Start with the thing your team already does by hand every week. Good first mods: redacting API keys and customer identifiers from tool output, denying shell commands outside the project directory, and prefixing every prompt in a regulated repository with the compliance notes that people forget. Each is a few lines, each removes a recurring mistake, and each shows whether the format fits your team before you commit to anything larger.

Sources: Customize Claude Code with mods (Anthropic, October 1, 2026); Claude Code changelog, versions 2.1.287 and 2.1.288.