Home Docs Claude Code CLI 20 Oct 2026

One change · claude-code

Mods overview changedplugins/mods/overview

Nearest release: v2.1.304, published 6 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 20 Oct 2026 02:14 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 18:07 UTC.

Upstream edited 20 Oct 2026 02:14 UTC

Recorded here 22 Oct 2026 18:07 UTC

Lines+47added

Lines−47removed

From line 2 where the diff opens

First seen 1 Oct 2026 this site's first read of the page

Recorded edits15to this page, all time

The whole hunk

from line 2, old and new numbered

lines

from line 2

33> Add panes, commands, and tool call rules to Claude Code with a mod. See what a mod can do, how to make or install one, and where mods run.

5A mod is a [plugin](/docs/en/plugins/overview) that changes how Claude Code looks and behaves. It's made of JavaScript or TypeScript event handlers: Claude Code calls one when an event happens, such as a tool call, a submitted prompt, or a part of the interface being drawn, and the handler can watch the event, change it, or take it over. Use a mod to add a feature of your own to Claude Code, such as a pane that charts how full your context is after each request. For the files in a mod and a complete example, see [How a mod works](#how-a-mod-works).

5A mod is a [plugin](/docs/en/plugins/overview.md) that changes how Claude Code looks and behaves. It's made of JavaScript or TypeScript event handlers: Claude Code calls one when an event happens, such as a tool call, a submitted prompt, or a part of the interface being drawn, and the handler can watch the event, change it, or take it over. Use a mod to add a feature of your own to Claude Code, such as a pane that charts how full your context is after each request. For the files in a mod and a complete example, see [How a mod works](#how-a-mod-works).

77> [!NOTE]

88>

9> Claude Code's existing [hooks](/docs/en/hooks) also run on events, as a shell command, HTTP request, or prompt you configure in a settings file. A mod's handlers are functions that run inside Claude Code instead. Claude Code calls both kinds hooks: on these pages, "hook" means a mod's handler, and the settings-file kind is a "settings hook".

9> Claude Code's existing [hooks](/docs/en/hooks.md) also run on events, as a shell command, HTTP request, or prompt you configure in a settings file. A mod's handlers are functions that run inside Claude Code instead. Claude Code calls both kinds hooks: on these pages, "hook" means a mod's handler, and the settings-file kind is a "settings hook".

1010

1111## What a mod can do

1212

1313Settings hooks, skills, status lines, and MCP servers work from outside Claude Code: each one runs a script, or gives Claude text or tools. A mod runs inside Claude Code, so it can do things they can't:

1414

15* **Draw an interface you can use**: a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields. See [Draw in the interface](/docs/en/plugins/mods/interface).

16* **Redraw Claude Code's own interface**: replace or restyle parts Claude Code draws itself, such as a tool call's row, the spinner, or the dialog Claude asks questions in. See [Change what Claude Code already draws](/docs/en/plugins/mods/interface#change-what-claude-code-already-draws).

17* **Step into a tool call or a request**: for example, hold a tool call while you ask the user a question, answer it without running the tool, or send one request to a different model. See [Guard or change a tool call](/docs/en/plugins/mods/events#guard-or-change-a-tool-call) and [Follow a turn](/docs/en/plugins/mods/events#follow-a-turn).

18* **Run your own code on a command**: a `/command` that runs your function at once, with no Claude turn, even while Claude is working. See [Add a command or a tool](/docs/en/plugins/mods/api#add-a-command-or-a-tool).

19* **Share data between hooks**: a mod's hooks share the variables in its file, so what one hook records, another can show. For example, one hook can count tool calls while another shows the count beside the spinner, or one can read each request's token usage while another charts it in a pane. See [React to events](/docs/en/plugins/mods/events).

15* **Draw an interface you can use**: a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields. See [Draw in the interface](/docs/en/plugins/mods/interface.md).

17* **Step into a tool call or a request**: for example, hold a tool call while you ask the user a question, answer it without running the tool, or send one request to a different model. See [Guard or change a tool call](/docs/en/plugins/mods/events.md#guard-or-change-a-tool-call) and [Follow a turn](/docs/en/plugins/mods/events.md#follow-a-turn).

2020

21Mods work in the Claude Code CLI, the Code tab of the Claude Desktop app, and the VS Code extension. See [Where mods run](#where-mods-run) for how they behave elsewhere, such as in `claude -p` and cloud sessions. If a settings hook, a skill, or an MCP server already does what you need, [compare them](#compare-mods-settings-hooks-skills-and-mcp-servers) before you write a mod. To manage mods for an organization, see [Manage mods for your organization](/docs/en/plugins/mods/admin).

2222

2323## Get a mod

2424

from line 25

2525To start with a mod:

2626

2727* **Use one you already have**: some of Claude Code's own features are mods, such as `/diff`. See [Mods built into Claude Code](#mods-built-into-claude-code).

28* **Make one**: describe what you want in a Claude Code session, and Claude writes the mod. See [Ask Claude for a mod](/docs/en/plugins/mods/create#ask-claude-for-a-mod). To learn how a mod's code works, [write one yourself](/docs/en/plugins/mods/create#write-a-mod-yourself).

28* **Make one**: describe what you want in a Claude Code session, and Claude writes the mod. See [Ask Claude for a mod](/docs/en/plugins/mods/create.md#ask-claude-for-a-mod). To learn how a mod's code works, [write one yourself](/docs/en/plugins/mods/create.md#write-a-mod-yourself).

2929* **Install one**: see [Install or update a mod](#install-or-update-a-mod), or [try a sample mod](#try-a-sample-mod)

3030

3131### Install or update a mod

from line 39

3939* In a Claude Code session, run `/plugin install token-chart@your-org`.

4040* In your shell, run `claude plugin install token-chart@your-org`.

4141

42[Install plugins](/docs/en/plugins/install) covers marketplaces, scopes, the VS Code extension and the Desktop app, and [keeping plugins updated](/docs/en/plugins/install#keep-plugins-updated), all of which apply to a plugin that contains a mod without changes.

42[Install plugins](/docs/en/plugins/install.md) covers marketplaces, scopes, the VS Code extension and the Desktop app, and [keeping plugins updated](/docs/en/plugins/install.md#keep-plugins-updated), all of which apply to a plugin that contains a mod without changes.

4343

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

4545

from line 53

5353

5454A sample mod runs with your permissions. To see what one does before you load it, [list its hooks and calls](#list-what-a-mod-does-before-you-install-one).

5555

56To try one, clone the repository and [load the mod's directory for one session](/docs/en/plugins/create#load-a-directory-or-archive-for-one-session) with `--plugin-dir`. To confirm the mod loaded, [check which mods the session loaded](#see-which-mods-a-session-loaded).

56To try one, clone the repository and [load the mod's directory for one session](/docs/en/plugins/create.md#load-a-directory-or-archive-for-one-session) with `--plugin-dir`. To confirm the mod loaded, [check which mods the session loaded](#see-which-mods-a-session-loaded).

5757

5858To keep one, [add the clone's `claude-code/mods` directory as a marketplace](/docs/en/plugins/install#add-a-marketplace), then install the mod from `claude-code-playground-mods`. The marketplace points at your clone, so the mod stops loading if you move or delete it.

5959

6060## Decide whether to trust a mod

6161

62A mod is code that runs with your permissions, inside Claude Code. Install mods only from authors and [marketplaces you trust](/docs/en/plugins/security).

62A mod is code that runs with your permissions, inside Claude Code. Install mods only from authors and [marketplaces you trust](/docs/en/plugins/security.md).

6363

6464### What a mod can reach

6565

from line 72

7272* **Act without asking you**: approve a tool call before you're asked

7373* **Spend your usage**: call a model on your plan or API key

7474

75Mods aren't sandboxed. If you turn on [sandboxing](/docs/en/sandboxing), the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it.

75Mods aren't sandboxed. If you turn on [sandboxing](/docs/en/sandboxing.md), the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it.

7676

77With [managed settings](/docs/en/settings#check-what-your-organization-enforces) or a Team or Enterprise [`/login`](/docs/en/authentication#authentication-precedence) as the session's credential, by default a mod's approval doesn't get a call past your `ask` rules or `PreToolUse` hooks. Without either, a mod can approve a call that an `ask` rule would prompt for, or that your `PreToolUse` hook blocked. To check when a mod can also approve a call that a `deny` rule refuses, see [Extend permissions with hooks](/docs/en/permissions#precedence-among-rules-hooks-and-mods).

77With [managed settings](/docs/en/settings.md#check-what-your-organization-enforces) or a Team or Enterprise [`/login`](/docs/en/authentication#authentication-precedence) as the session's credential, by default a mod's approval doesn't get a call past your `ask` rules or `PreToolUse` hooks. Without either, a mod can approve a call that an `ask` rule would prompt for, or that your `PreToolUse` hook blocked. To check when a mod can also approve a call that a `deny` rule refuses, see [Extend permissions with hooks](/docs/en/permissions.md#precedence-among-rules-hooks-and-mods).

7878

7979A mod can restyle much of Claude Code's interface, but not the permission prompt. It can't change what a prompt shows you.

8080

from line 86

8686claude plugin validate ./some-mod

8787```

8888

89The `hooks:` and `calls:` lines in the output list the events the mod handles and what it asks Claude Code to do. [Review what a mod can do](/docs/en/plugins/mods/admin#review-what-a-mod-can-do) shows the output and which calls to look for.

89The `hooks:` and `calls:` lines in the output list the events the mod handles and what it asks Claude Code to do. [Review what a mod can do](/docs/en/plugins/mods/admin.md#review-what-a-mod-can-do) shows the output and which calls to look for.

9090

9191## Turn mods on or off

9292

9393Mods are on by default. In the terminal, use Claude Code v2.1.287 or later. The Desktop app includes its own copy of Claude Code, and mods work there from v2.1.286. Check the version in the place you use mods:

9494

95* **Terminal**: in your shell, run `claude --version`. If yours is older, [update Claude Code](/docs/en/setup#update-claude-code).

96* **Desktop app**: in a local session in the Code tab, enter `/status` and read the **Claude Code** row, which shows a version such as `2.1.286`. If yours is older, [update the Desktop app](/docs/en/desktop#claude-code-version-in-the-code-tab).

95* **Terminal**: in your shell, run `claude --version`. If yours is older, [update Claude Code](/docs/en/setup.md#update-claude-code).

9797

9898To turn mods off, choose how many to stop, and for how long. To turn them back on, undo the same change:

9999

from line 101

101101* **Every installed mod, for one session**: start Claude Code with [`--safe-mode`](/docs/en/cli-reference#cli-flags), which also disables your other customizations

102102* **Every mod you installed, in every session**: set [`"disableAllHooks": true`](/docs/en/settings-reference#disableallhooks) in `~/.claude/settings.json`. Your settings hooks and custom status line stop too. What your organization manages keeps running.

103103

104If you use Claude Code through an organization, an administrator can also limit which mods load. Administrators start at [Stop user-installed mods from loading](/docs/en/plugins/mods/admin#stop-user-installed-mods-from-loading).

105105

106106`disableAllHooks` and your 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 load. Other settings and flags reach further. [`disableAllHooks`](/docs/en/settings-reference#disableallhooks) and [What runs under `allowManagedHooksOnly`](/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) list what each one does to a plugin and its settings hooks.

107107

108To find out whether mods can load for you, see [Check whether mods can load](/docs/en/plugins/mods/troubleshoot#check-whether-mods-can-load).

108To find out whether mods can load for you, see [Check whether mods can load](/docs/en/plugins/mods/troubleshoot.md#check-whether-mods-can-load).

109109

110110> [!NOTE]

111111>

from line 113

113113

114114### See which mods a session loaded

115115

116To see which mods a terminal session loaded, run `/plugin` at the Claude Code prompt. A dim line under the tabs gives the count and the names, such as `1 mod active · first-mod`. If a mod you installed isn't named there, see [Find out why a mod does nothing](/docs/en/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing).

117117

118118## How a mod works

119119

120A mod is a [plugin](/docs/en/plugins/overview) whose code registers event handlers, called hooks. Claude Code runs a hook when its event happens, such as when Claude calls a tool or when the spinner is drawn. A small mod has three files:

120A mod is a [plugin](/docs/en/plugins/overview.md) whose code registers event handlers, called hooks. Claude Code runs a hook when its event happens, such as when Claude calls a tool or when the spinner is drawn. A small mod has three files:

121121

122122```text theme={null}

123123first-mod/

from line 128

128128 └── register.js

129129```

130130

131* **`plugin.json`**: the plugin's [manifest](/docs/en/plugins/manifest-reference)

132* **`hooks.json`**: [points to your code file](/docs/en/plugins/mods/reference#files)

133* **`register.js`**: [your code](/docs/en/plugins/mods/create#write-a-mod-yourself), called the hooks module. It tells Claude Code which events to run your functions on.

131* **`plugin.json`**: the plugin's [manifest](/docs/en/plugins/manifest-reference.md)

132* **`hooks.json`**: [points to your code file](/docs/en/plugins/mods/reference.md#files)

133* **`register.js`**: [your code](/docs/en/plugins/mods/create.md#write-a-mod-yourself), called the hooks module. It tells Claude Code which events to run your functions on.

134134

135135This is a complete `register.js`. It counts the tool calls Claude makes and shows the count beside the spinner while Claude works, as in `Thinking · tool calls: 3…`.

136136

from line 176

176176

177177To do anything outside its own code, such as draw, add a command, call a model, read a file, start a process, or make a network request, a hook calls the mods API. A hook has no other way to do those things, which is why Claude Code can [list what a mod does](#list-what-a-mod-does-before-you-install-one) before you install it.

178178

179For the code behind each choice, see [React to events](/docs/en/plugins/mods/events#how-a-hook-handles-an-event). For what a hook can call, see [Use the mods API](/docs/en/plugins/mods/api).

179For the code behind each choice, see [React to events](/docs/en/plugins/mods/events.md#how-a-hook-handles-an-event). For what a hook can call, see [Use the mods API](/docs/en/plugins/mods/api.md).

180180

181181### Where mods run

182182

from line 185

185185| Where you run Claude Code | Hooks run | What the mod draws appears |

186186| :- | :- | :- |

187187| `claude` in a terminal, including an editor's integrated terminal and the JetBrains plugin | Yes | Yes |

188| The Code tab of the Desktop app, except in a WSL session | Yes | Yes, except elements the [elements table](/docs/en/plugins/mods/reference#elements) marks terminal-only |

189| A [WSL session](/docs/en/desktop-wsl) in the Desktop app | No, because plugins aren't available in WSL sessions | No |

190| The VS Code extension's chat panel | Yes | Yes, with extension version 2.1.299 or later. A session that [doesn't fetch feature flags](/docs/en/env-vars#features-that-need-feature-flag-fetching), such as one on Amazon Bedrock, needs 2.1.304 or later. The [render sites](/docs/en/plugins/mods/reference#render-sites) and [elements](/docs/en/plugins/mods/reference#elements) tables mark what the panel draws. |

191| `claude -p` and the [Agent SDK](/docs/en/agent-sdk/overview) | Yes | No |

192| [Remote Control](/docs/en/remote-control) from claude.ai or the mobile app | Yes, in the session on your machine | In the terminal on your machine |

193| A [cloud session](/docs/en/claude-code-on-the-web) | Yes, for a plugin that [reaches the cloud session](/docs/en/cloud-environments#what-carries-over-from-your-setup) | No |

188| The Code tab of the Desktop app, except in a WSL session | Yes | Yes, except elements the [elements table](/docs/en/plugins/mods/reference.md#elements) marks terminal-only |

189| A [WSL session](/docs/en/desktop-wsl.md) in the Desktop app | No, because plugins aren't available in WSL sessions | No |

190| The VS Code extension's chat panel | Yes | Yes, with extension version 2.1.299 or later. A session that [doesn't fetch feature flags](/docs/en/env-vars.md#features-that-need-feature-flag-fetching), such as one on Amazon Bedrock, needs 2.1.304 or later. The [render sites](/docs/en/plugins/mods/reference.md#render-sites) and [elements](/docs/en/plugins/mods/reference.md#elements) tables mark what the panel draws. |

191| `claude -p` and the [Agent SDK](/docs/en/agent-sdk/overview.md) | Yes | No |

192| [Remote Control](/docs/en/remote-control.md) from claude.ai or the mobile app | Yes, in the session on your machine | In the terminal on your machine |

193| A [cloud session](/docs/en/claude-code-on-the-web.md) | Yes, for a plugin that [reaches the cloud session](/docs/en/cloud-environments.md#what-carries-over-from-your-setup) | No |

194194

195195A mod that draws can check which app it's running in, and fall back to a line in the transcript or a command's text reply where nothing draws.

196196

197197## Control mods for your organization

198198

199Administrators decide whether mods run and which ones, through [managed settings](/docs/en/managed-settings). [Manage mods for your organization](/docs/en/plugins/mods/admin) covers what happens by default, how to review a mod, and how to enforce a policy with a mod of your own.

199Administrators decide whether mods run and which ones, through [managed settings](/docs/en/managed-settings.md). [Manage mods for your organization](/docs/en/plugins/mods/admin.md) covers what happens by default, how to review a mod, and how to enforce a policy with a mod of your own.

200200

201201## Compare mods, settings hooks, skills, and MCP servers

202202

from line 210

211211| Pick it when | You want a pane, a band above the prompt, a custom command, or to rewrite an event | You want to block, allow, or log an event with a script you already have | You keep pasting the same instructions into chat | Claude needs to reach an external system |

212212

213Each of the others has its own page: [Hooks](/docs/en/hooks), [Skills](/docs/en/skills), and [MCP](/docs/en/mcp). A plugin can hold all of them, so a mod can ship in the same plugin as a skill and an MCP server.

213Each of the others has its own page: [Hooks](/docs/en/hooks.md), [Skills](/docs/en/skills.md), and [MCP](/docs/en/mcp.md). A plugin can hold all of them, so a mod can ship in the same plugin as a skill and an MCP server.

214214

215215## Mods built into Claude Code

216216

from line 220

220220

222222| :- | :- | :- | :- |

223| `cc-plugin-agents-md` | Loads `AGENTS.md` as project instructions | Every session, apart from [the ones that can't read `AGENTS.md`](/docs/en/memory#when-agents-md-support-is-unavailable) | Disable it in `/plugin`, or [choose which instruction files load](/docs/en/memory#choose-which-instruction-files-load) |

224224| `cc-plugin-diff` | Takes over [`/diff`](/docs/en/interactive-mode#review-changes-with-%2Fdiff) and draws its pane | Interactive terminal sessions | Disable it in `/plugin`. `/diff` stays, and Claude Code's built-in version of the command answers it. |

225225| `cc-plugin-plugin-authoring` | Gives Claude the [`plugin-authoring` skill](/docs/en/plugins/mods/create#ask-claude-for-a-mod) for writing mods. It holds a skill and no mod code. | Unless Anthropic has turned installed mods off remotely | Disable it in `/plugin` |

226| `cc-plugin-sec-default` | Guards what your organization manages from the mods a user installs | [Where the guard loads](/docs/en/plugins/mods/admin#know-what-happens-by-default) | You can't. An administrator [sets the order](/docs/en/plugins/mods/admin#install-your-organizations-mods) in managed settings |

226| `cc-plugin-sec-default` | Guards what your organization manages from the mods a user installs | [Where the guard loads](/docs/en/plugins/mods/admin.md#know-what-happens-by-default) | You can't. An administrator [sets the order](/docs/en/plugins/mods/admin.md#install-your-organizations-mods) in managed settings |

227227| `cc-plugin-telemetry` | Sends the analytics records that Claude Code and its built-in mods log | Wherever Claude Code's own analytics are on | Disable it in `/plugin`, or turn analytics off, for example with [`DISABLE_TELEMETRY`](/docs/en/env-vars) |

228| `cc-plugin-you-should-know` | [You should know](/docs/en/interactive-mode#you-should-know-suggestions): a side agent shows a note above the prompt when it finds something you might have missed | Off until you [turn it on](/docs/en/interactive-mode#you-should-know-suggestions) | Disable it in `/plugin` |

228| `cc-plugin-you-should-know` | [You should know](/docs/en/interactive-mode.md#you-should-know-suggestions): a side agent shows a note above the prompt when it finds something you might have missed | Off until you [turn it on](/docs/en/interactive-mode.md#you-should-know-suggestions) | Disable it in `/plugin` |

229229

230230The settings and flags that stop installed mods, such as `disableAllHooks`, `--bare`, and `--safe-mode`, don't stop built-in mods.

231231

from line 235

235235

236236* [`diff`](https://github.com/anthropics/claude-code/tree/main/mods/diff): the `/diff` pane, with buttons bound to keyboard actions and scrolling the mod handles itself

237237* [`agents-md`](https://github.com/anthropics/claude-code/tree/main/mods/agents-md): loads `AGENTS.md` as project instructions, with a [`userConfig`](/docs/en/plugins/components#user-configuration) option

238* [`sec-default`](https://github.com/anthropics/claude-code/tree/main/mods/sec-default): the guard described in [Know what happens by default](/docs/en/plugins/mods/admin#know-what-happens-by-default), a model for a mod that enforces policy

238* [`sec-default`](https://github.com/anthropics/claude-code/tree/main/mods/sec-default): the guard described in [Know what happens by default](/docs/en/plugins/mods/admin.md#know-what-happens-by-default), a model for a mod that enforces policy

239239* [`telemetry`](https://github.com/anthropics/claude-code/tree/main/mods/telemetry): adds methods that other mods can call, and ships their types

240240

241241## Next steps

242242

243* [Create a mod](/docs/en/plugins/mods/create): build one that counts tool calls, shows the count beside the spinner, and adds a command, and learn the edit and reload loop

244* [Draw in the interface](/docs/en/plugins/mods/interface): panes, the band above the prompt, buttons, text fields, and state

245* [React to events](/docs/en/plugins/mods/events): tool calls, prompts, turns, and the order mods run in

246* [Use the mods API](/docs/en/plugins/mods/api): commands, tools, model calls, timers, and files

247* [Test a mod](/docs/en/plugins/mods/test): automated tests that run without a session

248* [Troubleshoot a mod](/docs/en/plugins/mods/troubleshoot): the reasons a mod does nothing, and the debug log

249* [Manage mods for your organization](/docs/en/plugins/mods/admin): defaults, managed settings, reviewing a mod, and policy mods

250* [Mods reference](/docs/en/plugins/mods/reference): events, methods, elements, and limits

243* [Create a mod](/docs/en/plugins/mods/create.md): build one that counts tool calls, shows the count beside the spinner, and adds a command, and learn the edit and reload loop

244* [Draw in the interface](/docs/en/plugins/mods/interface.md): panes, the band above the prompt, buttons, text fields, and state

245* [React to events](/docs/en/plugins/mods/events.md): tool calls, prompts, turns, and the order mods run in

246* [Use the mods API](/docs/en/plugins/mods/api.md): commands, tools, model calls, timers, and files

247* [Test a mod](/docs/en/plugins/mods/test.md): automated tests that run without a session

248* [Troubleshoot a mod](/docs/en/plugins/mods/troubleshoot.md): the reasons a mod does nothing, and the debug log

249* [Manage mods for your organization](/docs/en/plugins/mods/admin.md): defaults, managed settings, reviewing a mod, and policy mods

250* [Mods reference](/docs/en/plugins/mods/reference.md): events, methods, elements, and limits

251251

This page’s history 15 edits

20 Oct 2026 +47 −47 · this one
20 Oct 2026 +10 −14
20 Oct 2026 +1 −1
19 Oct 2026 +1 −1
15 Oct 2026 +3 −3
14 Oct 2026 +2 −2

The page’s own history →

Where it came from

The captureclaude-code
Upstream pagecode.claude.com

Around it

Every changethe ledger
That day20 Oct 2026