Claude Code Mods: Plugins That Can Change How Claude Code Itself Behaves

Until this week, a Claude Code plugin could hand Claude more to work with: a skill, a slash command, an MCP server, a hook that ran a shell script. What a plugin could not do was change how Claude Code itself behaved. You could add tools to the shop. You could not move the walls.

On October 1, Anthropic shipped Claude Mods in Claude Code v2.1.287. The changelog line is short: "plugins may now modify deeper behavior." That one sentence is a bigger change than it sounds, so here is my read on what it means for people who run Claude Code for real work.

A note on sourcing: I'm working from the official changelog, Anthropic's announcement coverage (The New Stack quotes the team saying there is "no reason why everyone should have an identical Claude experience"), and the type definitions that ship with the CLI. Treat the specifics below as the state of things on October 5, because this surface is moving fast.

What a mod actually is

A mod is a normal plugin with one new trick: its code runs inside Claude Code as TypeScript, wrapping the engine's own events. Each hook receives the event, and a next function that runs everything beneath it (other plugins, then Claude Code's built-in behavior). That gives you three moves:

• Answer for yourself. Return without calling next and your result wins. Block a tool call, for example.
• Rewrite and pass along. Call next with a modified copy of the event, and the rest of the stack sees your version.
• Call next and react. Let the real thing happen, then act on what came back.

If you've written Express middleware, you already know the shape. The difference from the old shell-script hooks is where you sit. A classic hook reacts after the fact, in a separate process. A mod sits in the path.

What it looks like in code

A mod lives in a plugin folder with the usual manifest, plus a hooks/hooks.json that points at one TypeScript module. Here is the kind of thing the official examples show: protect your secrets file from edits, and flag failed shell commands in the status line.

import type { Register } from 'claude-code'
 
const PROTECTED = /(^|\/)\.env(\.|$)/
 
export const register: Register = on => {
  on('tool.call', { tool: 'Edit' }, ($, e, next) =>
    PROTECTED.test(e.file_path)
      ? { deny: `${$.plugin.name}: ${e.file_path} is protected here.` }
      : next(e),
  )
 
  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
    const ran = await next({ ...e, command: e.command.trim() })
    const hasFailed = ran.deny === undefined && ran.isError === true
    $.ui.status(hasFailed ? `failed: ${e.command.slice(0, 40)}` : undefined)
    return ran
  })
}

That's about fifteen lines. The first hook is a hard rule Claude cannot talk its way around, because the call never reaches the tool. The second watches a result and puts a one-line signal in the status line. Compare that with a prompt in CLAUDE.md saying "please don't touch .env." One is a request. The other is a lock.

The parts that go beyond hooks

Hooks on tool calls are the part I understand best, but mods reach further. From the changelog and the type definitions:

• UI. A mod can draw a pane, a band above the prompt, a toast, or a status line entry, using a ui.render hook. It works across the terminal and desktop app.
• Prompts. You can rewrite a prompt before it's submitted, or add a section to the system prompt.
• Commands and tools. A mod can register slash commands and tools the model can call, plus work on timers.
• Built-in example. Anthropic ships one called "You should know," a side agent that watches the session and flags things you or Claude might miss. You enable it with /plugin enable cc-plugin-you-should-know@builtin (the changelog says it's for first-party sessions with telemetry on).

Mods ship inside plugins, so they go through the same sharing path as everything else: a plugin directory, a team marketplace, a folder you point Claude Code at.

Why I care, practically

I run Claude Code against a business with real money and real customer data in it. My guardrails today are a mix of CLAUDE.md rules and permission settings. The rules work most of the time, and "most of the time" is a strange standard for something like "never send marketing email to a B2B lead." Mods give me a place to put the rules that must hold every time. Three I would build first:

1. A protected-paths mod. Deny edits to env files, lockfiles and generated files, with a message that tells Claude what to do instead.
2. A "done means verified" band. A one-line row above the prompt that shows whether the last build or test run passed, so I stop assuming.
3. A team default. One shared plugin that gives every engineer on a team the same guardrails, instead of each person's private settings drifting apart.

Cautions

Mods are powerful, and the changelog already hints at why. One recent fix stops a user-installed plugin from rewriting the descriptions of an organization-managed MCP server's sign-in tools. That is exactly the class of problem you should expect when third-party code sits inside the tool-call path. Read what a mod hooks before you install it, the same way you'd read a browser extension's permissions. Start with mods you write yourself or from sources you trust, and use claude plugin validate on a folder, which reports what the module hooks and calls.

The other caution is about timing. Parts of this surface were described as proposals only a few weeks ago, so expect names and details to shift between versions. Pin your Claude Code version in anything a team depends on.

Where I'd start

If you only do one thing this week: update to v2.1.287 or later, then write the protected-paths mod above and try to get Claude to edit a .env file. Watching it get stopped by code rather than by a polite instruction is the fastest way to feel the difference.

If you want to go deeper on the plugin side first, I wrote up how the plugin eval command works and the official plugins directory. Mods build on both.