# Claude Code now runs mods: what they change and what they can reach

Canonical: https://clawdocx.com/blog/claude-code-mods
Author: Mira Castellan
Published: 2026-10-03
Updated: 2026-10-03

> Anthropic shipped mods in Claude Code v2.1.287 on 1 October 2026. They run inside the agent with your permissions, unsandboxed, and here is what they reach.

Anthropic added mods to Claude Code in v2.1.287, published on 1 October 2026, and they are on by default. A mod is a plugin whose code runs inside Claude Code and can redraw its interface, intercept a tool call, or answer a prompt before the model sees it. The part worth reading twice is the trust boundary: mods are not sandboxed, they run with your permissions, and Anthropic's own documentation says to install them only from authors and marketplaces you trust.

## What is a mod, and how is it different from a hook?

Anthropic's announcement describes mods as small TypeScript functions that change how Claude Code works, and lists what one can do: "rewrite a prompt, add new UI, replace a built-in feature, or add entirely new functionality". The documentation is broader about the language, calling a mod a plugin made of "JavaScript or TypeScript event handlers".

The naming is genuinely confusing, and the docs acknowledge it. Claude Code already had hooks: shell commands, HTTP requests or prompts you configure in a settings file. Claude Code calls both kinds hooks, so the documentation draws the line by name: on the mods pages, "hook" means a mod's handler, and the settings-file kind is a "settings hook". The difference that matters is where the code runs. A settings hook runs a script outside Claude Code. A mod's handler is a function that runs inside it.

That is what lets a mod do things the older extension points cannot. Per the documentation, a mod can:

- **Draw an interface you can use**, such as a pane beside the transcript or a band above the prompt, with tabs, buttons and text fields.
- **Redraw Claude Code's own interface**, replacing or restyling parts it draws itself, such as a tool call's row, the spinner, or the dialog Claude asks questions in.
- **Step into a tool call or a request**, for example holding a tool call while it asks you a question, answering it without running the tool, or sending one request to a different model.
- **Run your own code on a command**, as a `/command` that runs your function at once with no Claude turn, even while Claude is working.
- **Share data between hooks**, because a mod's hooks share the variables in its file, so one hook can count tool calls while another displays the count.

A hook gets the event before Claude Code acts on it, so the documentation describes three choices: observe it and let it continue, rewrite it before it continues, or answer it so the usual behaviour never runs.

## How do mods compare to settings hooks, skills and MCP servers?

The documentation includes its own comparison, which is the clearest statement of when each one is the right tool.

| | Mod | Settings hook | Skill | MCP server |
|---|---|---|---|---|
| What it is | Functions in a plugin that Claude Code calls in its own process | A shell command, HTTP request or prompt run on a lifecycle event | A `SKILL.md` file of instructions Claude reads | An external process or service that gives Claude tools |
| What you write | JavaScript or TypeScript | A script and a `settings.json` entry | Markdown | A server in any language |
| Can it draw in the interface | Yes | No | No | No |
| What it can change | Tool calls, prompts, commands, turns, and what the interface draws | Whether a tool call or prompt goes ahead, a call's arguments and result, context added for Claude | What Claude knows and does | Which tools Claude has |

A plugin can hold all of them, so a mod can ship in the same plugin as a skill and an MCP server. If you are still placing these against each other, our breakdown of [skills, subagents, plugins and MCP servers](/blog/claude-code-skills-vs-subagents-vs-plugins-vs-mcp) covers the older four, and the [hooks beginners guide](/blog/claude-code-hooks-beginners-guide) covers settings hooks specifically.

## What can a mod reach?

This is the section to read before you install anything. The documentation is unusually direct about it: a mod is code that runs with your permissions, inside Claude Code. Once it loads, it can:

| What it can do | What that means in practice |
|---|---|
| Act on your machine as you | Read and write files anywhere your user account can, start programs, make network requests |
| Read your secrets | Environment variables and settings files, including an API key you keep in either |
| See your session | Every prompt you send and every tool call Claude makes |
| Change your session | Rewrite a prompt or a tool call, submit a prompt as if you had typed it, or message another of your sessions |
| Act without asking you | Approve a tool call before you are asked |
| Spend your usage | Call a model on your plan or API key |

Two details sharpen that further. Mods are not sandboxed: the documentation notes that if you turn sandboxing on, the sandbox isolates the Bash commands Claude runs, and a process a mod starts runs outside it. And a mod that approves tool calls can approve one that an `ask` rule would have prompted for, or that one of your own `PreToolUse` hooks blocked.

There is one line a mod cannot cross. It can restyle much of the interface, but not the permission prompt: per the documentation, it cannot change what a prompt shows you.

Before installing, you can inspect a mod without running it. Get the plugin's files, then run `claude plugin validate` on its directory:

```bash
claude plugin validate ./some-mod
```

The `hooks:` and `calls:` lines list the events it handles and what it asks Claude Code to do. The same caution we apply to third-party skills applies here, and more so, because a mod is executable code rather than instructions: see our [skill security audit](/docs/skill-security-audit) for how to read someone else's extension before trusting it. ClawDocx does not vet or endorse any third-party mod.

## How do you install, disable, or audit mods?

A mod installs as a plugin from a marketplace, named as plugin, `@`, marketplace:

```bash
# in a Claude Code session
/plugin install token-chart@your-org

# or in your shell
claude plugin install token-chart@your-org
```

If you install or update from the shell while a session is open, run `/reload-plugins` in that session. Otherwise it loads next time you start Claude Code.

Turning them off has three scopes, per the documentation:

| Scope | How |
|---|---|
| One mod | Disable or uninstall its plugin from the **Installed** tab in `/plugin` |
| Every installed mod, one session | Start with `--safe-mode`, which also disables your other customizations |
| Every mod you installed, every session | Set `"disableAllHooks": true` in `~/.claude/settings.json` |

`disableAllHooks` and an organization's `allowManagedModsOnly` stop a mod and leave the rest of its plugin in place: the plugin stays installed, and its skills, commands, agents and MCP servers still load. Administrators can limit which mods load through managed settings.

If you set `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` during early access, the documentation says to remove it. From v2.1.287 Claude Code ignores it, so setting it to `0` does not keep mods off.

## Which of Claude Code's own features are already mods?

Some are, which is the clearest signal of how far the interface has been opened up. The announcement notes the built-in `/diff` feature is now a mod, so you can disable or replace it the way you would any third-party extension. The documentation lists the built-ins by the name `/plugin` shows:

| Name in `/plugin` | What it does |
|---|---|
| `cc-plugin-agents-md` | Loads `AGENTS.md` as project instructions |
| `cc-plugin-diff` | Takes over `/diff` and draws its pane |
| `cc-plugin-plugin-authoring` | Gives Claude the `plugin-authoring` skill for writing mods |
| `cc-plugin-sec-default` | Guards what your organization manages from the mods a user installs |
| `cc-plugin-telemetry` | Sends the analytics records Claude Code and its built-in mods log |
| `cc-plugin-you-should-know` | Runs a side agent that notes things worth knowing during longer tasks. Disabled by default |

The settings and flags that stop installed mods do not stop built-in ones. On Team and Enterprise plans, the announcement says the `sec-default` mod loads first, to stop mods that users install from doing risky things. Anthropic publishes the source of several built-ins, `diff`, `agents-md`, `sec-default` and `telemetry`, in the `mods` directory of the Claude Code repository.

## Where do mods actually run?

A mod's hooks run in every kind of session that loads the plugin, but drawing is narrower. Only the terminal and the Desktop app show a mod's panes, bands and replaced rows.

| Where you run Claude Code | Hooks run | Drawing appears |
|---|---|---|
| `claude` in a terminal | Yes | Yes |
| The Code tab of the Desktop app, except a WSL session | Yes | Mostly, apart from terminal-only elements |
| A WSL session in the Desktop app | No, plugins are unavailable there | No |
| The VS Code extension's chat panel | Yes | No |
| `claude -p` and the Agent SDK | Yes | No |
| A cloud session | Yes, for a plugin that reaches the session | No |

So a mod written for a pane degrades quietly in the VS Code panel or a non-interactive run: its hooks still fire, and whatever it wanted to draw does not appear. The documentation suggests a mod check which app it is running in and fall back to a line in the transcript.

## What should you do about it this week?

If you run Claude Code on a machine with credentials on it, three things are worth doing now. Check your version with `claude --version`, because mods are on by default from v2.1.287 and you may already be running them. Open `/plugin` and look at the **Installed** tab, so you know which mods a session loads and which are built in. And treat any third-party mod as code you are installing on your machine rather than a configuration file, because that is exactly what Anthropic's documentation says it is.

For the current facts on the platform itself, the [Claude Code hub](/ai-agents/claude-code) is where we keep them verified.

## What we could not confirm

Anthropic's announcement post carries the date 1 October 2026 but no time of day. The timestamp this article relies on is the one on the v2.1.287 release, 1 October at 18:00, which is also the version the documentation names as the floor for mods.

The announcement calls a mod a small TypeScript function, while the documentation describes a mod's handlers as JavaScript or TypeScript. This article follows the documentation, since it is the more specific statement, and nothing here turns on the distinction.

We did not test a mod. Nothing in this article describes behaviour we observed on a machine: every statement above is drawn from Anthropic's announcement, its mods documentation, and the release entry for v2.1.287.

## Frequently asked questions

**What is a Claude Code mod?**

A mod is a plugin that changes how Claude Code looks and behaves. Anthropic's documentation describes it as JavaScript or TypeScript event handlers that Claude Code calls when something happens, such as a tool call, a submitted prompt, or a part of the interface being drawn. The handler can watch the event, change it, or take it over.

**Which version of Claude Code do mods need?**

The documentation states: "Mods require Claude Code v2.1.287 or later, and they're on by default." That release was published on 1 October 2026. Run `claude --version` to check which version you have.

**Are Claude Code mods sandboxed?**

No. Anthropic's documentation says plainly that mods are not sandboxed and that a mod runs with your permissions. If you turn sandboxing on, it isolates the Bash commands Claude runs, and a process a mod starts runs outside it.

**How do you install a mod?**

A mod installs as a plugin from a marketplace. In a session you run `/plugin install <name>@<marketplace>`, or in your shell `claude plugin install <name>@<marketplace>`. If you install from the shell while a session is open, run `/reload-plugins` in that session to load it.

**How do you turn mods off?**

The documentation gives three scopes: disable or uninstall a single mod's plugin from the Installed tab in `/plugin`, start Claude Code with `--safe-mode` to stop every installed mod for one session, or set `"disableAllHooks": true` in `~/.claude/settings.json` for every session. `--safe-mode` and `disableAllHooks` do not stop the mods built into Claude Code. Those are turned off one at a time in `/plugin`, except `cc-plugin-sec-default`, which you cannot turn off.

**Can you see what a mod does before installing it?**

Yes. Get the plugin's files, then run `claude plugin validate ./some-mod` in your shell. The `hooks:` and `calls:` lines in the output list the events the mod handles and what it asks Claude Code to do, without running it.

## Sources

- [Anthropic: Customize Claude Code with mods in TypeScript](https://claude.com/blog/claude-code-mods)
- [Claude Code docs: Mods overview](https://code.claude.com/docs/en/plugins/mods/overview)
- [Claude Code release v2.1.287](https://github.com/anthropics/claude-code/releases/tag/v2.1.287)
- [Claude Code releases on GitHub](https://github.com/anthropics/claude-code/releases)