Short answer: A mod is a Claude Code plugin whose code is made of JavaScript or TypeScript functions that Claude Code calls when events happen: a tool call, a submitted prompt, a part of the interface being drawn. It runs inside the Claude Code process, so it can do things a skill, a settings hook or an MCP server cannot, such as draw a pane beside the transcript or hold a tool call. You install a mod like any other plugin from a marketplace, or you describe the one you want in a session and let Claude write it.
Mod, settings hook, skill, MCP server
The docs call a mod’s functions hooks. The shell commands and HTTP requests you configure in a settings file are also called hooks, but on the mods pages they are settings hooks. What each one is good for:
| 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 Claude Code runs on a lifecycle event | A SKILL.md file of instructions Claude reads | An external process or service that gives Claude tools |
| What it can change | Tool calls, prompts, commands, turns, and what the interface draws | Whether a tool call or prompt goes ahead, a tool call’s arguments and result, context added for Claude | What Claude knows and does | Which tools Claude has |
| Can it draw in the interface | Yes | No | No | No |
| What you write | JavaScript or TypeScript | A script and a settings.json entry | Markdown | A server in any language |
One plugin can hold all of them, so a mod can ship in the same package as a skill and an MCP server.
What you need
Mods are on by default, so there is nothing to switch on. You only need a current version:
- Terminal: Claude Code v2.1.287 or later. Run
claude --versionin your shell. - Desktop app: it includes its own copy of Claude Code, where mods work from 2.1.286. In a local session in the Code tab, enter
/statusand read the Claude Code row.
To find out whether mods can load for you at all, run this from a directory that holds no mod:
claude plugin test| Message includes | What it means |
|---|---|
no hooks module to load | Mods can load, there just isn’t one here |
hooks modules are turned off here | disableAllHooks in your own settings, or your organization’s policy, is blocking them |
the rollout switch served off | Anthropic has turned installed mods off remotely |
the rollout switch was saved off by an earlier session | The value comes from an earlier session and may be out of date. Start claude once, then run the command again |
If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it. Claude Code v2.1.287 and later ignores it, so setting it to 0 no longer keeps mods off.
Where a mod runs
A mod’s hooks run in every kind of session that loads the plugin. Drawing happens in two places only:
| Where you run Claude Code | Hooks | What the mod draws |
|---|---|---|
claude in a terminal, including an editor’s integrated terminal and the JetBrains plugin | Yes | Yes |
| The Code tab of the Desktop app, except in a WSL session | Yes | Yes, apart from the elements that are terminal-only |
| A WSL session in the Desktop app | No, plugins aren’t available there | No |
| The VS Code extension’s chat panel | Yes | No |
claude -p and the Agent SDK | Yes | No |
| Remote Control from claude.ai or the mobile app | Yes, in the session on your machine | In the terminal on your machine |
| A cloud session | Yes, for a plugin that reaches the cloud session | No |
A mod can check which app it is running in and, where nothing draws, fall back to a line in the transcript or a command’s text reply.
Install a mod
A mod arrives as a plugin from a marketplace. Give the plugin’s name, an @, and the marketplace’s name:
# in a Claude Code session
/plugin install token-chart@your-org
# in your shell
claude plugin install token-chart@your-orgIf you install or update from your shell while a session is open, run /reload-plugins in that session to load the mod there. Otherwise it loads the next time you start Claude Code.
Check what it can reach before you install it
A mod is code that runs with your permissions, and it is not sandboxed. Once it loads, it can read and write files anywhere your user account can, start programs and make network requests. It can read environment variables and settings files, including an API key you keep in either, see every prompt you send and every tool call Claude makes, rewrite a prompt or a tool call, approve a tool call before you are asked, and spend your usage on model calls. If you turn on sandboxing, the sandbox covers the Bash commands Claude runs; a process a mod starts runs outside it.
So install only from authors and marketplaces you trust. One command lists which events a mod handles and what it asks Claude Code to do, without running the code. Get the plugin’s files first, for example with git clone:
claude plugin validate ./some-modThe hooks: and calls: lines in the output are the answer.
One thing a mod cannot do: change the permission prompt. What it shows you is what you get. And if a mod approves a call that a deny rule refuses, the call stays denied, and the built-in guard logs tried to lift a deny rule in your settings.
Have Claude write a mod
Describe what you want in an interactive session, for example: make a mod that shows the current git branch above the prompt. Claude works from a built-in skill named plugin-authoring, which you can also load yourself with /plugin-authoring.
- Describe it. Claude writes the mod into a directory of its own under
~/.claude/dev-mods/<session-id>/<name>/. In thedefaultandacceptEditspermission modes, Claude Code asks before each single file, because~/.claudeis a protected path. - Approve it. When Claude saves the first file, Claude Code asks whether to enable hot reloading for the session. With Enable for this session, the mods load when the turn ends and reload after every change; the answer lasts for the session, including after you resume it. With Not now, the files stay where Claude wrote them and load the next time that session starts.
- Check it. Enter
/pluginand press Tab until the Installed tab is selected. The mod is listed there, and that is also where you turn it off. - Keep it. A mod written this way loads only in the session that made it, and Claude Code deletes that session’s mods folder once it is older than
cleanupPeriodDays. Copy the directory somewhere of your own, such as~/mods/git-branch, and load it from there withclaude --plugin-dir ~/mods/git-branch. For other people, add it to a marketplace.
A mod Claude writes does not load when nobody is there to approve it (claude -p, dontAsk mode), when you haven’t accepted the trust prompt for the directory, or when mods are disabled.
Sample mods to try
Anthropic shares sample mods in the claude-code/mods directory of the claude-code-playground repository. Each one is a complete plugin, and its README says how it was built. They come as they are, without support.
token-weatherdraws a forecast of your context window above the prompt.blast-radiusholds a risky shell command, such asrm -rfor a force push, shows what it would change, and gives you two buttons.replay-theateradds a/replaycommand that steps through the file edits Claude made in the last turn.
A sample mod runs with your permissions too. Clone the repository, look at what it holds with claude plugin validate, then load the directory for one session:
claude --plugin-dir <path-to-clone>/claude-code/mods/<name>To keep one, add your clone’s claude-code/mods directory as a marketplace and 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.
The built-in mods
Some of Claude Code’s own features are mods, /diff among them. /plugin lists them in the Installed tab under Built-in. You can’t update or uninstall them, and the mods active line leaves them out.
Name in /plugin | What it does | How to turn it off |
|---|---|---|
cc-plugin-agents-md | Loads AGENTS.md as project instructions | Disable it in /plugin, or choose which instruction files load |
cc-plugin-diff | Takes over /diff and draws its pane | Disable it in /plugin. /diff stays, and Claude Code’s built-in version of the command answers it |
cc-plugin-plugin-authoring | Gives Claude the plugin-authoring skill for writing mods; holds no mod code itself | Disable it in /plugin |
cc-plugin-sec-default | Guards what your organization manages from the mods a user installs | You can’t. An administrator sets the order in managed settings |
cc-plugin-telemetry | Sends the analytics records Claude Code and its built-in mods log | Disable it in /plugin, or turn analytics off, for example with DISABLE_TELEMETRY |
cc-plugin-you-should-know | Runs a side agent during longer tasks and shows a note above the prompt when it finds something you might miss | Disable it in /plugin. Off by default, enable it with /plugin enable cc-plugin-you-should-know@builtin |
The source of some of these is public in the mods directory of the Claude Code repository, each with its hooks module and tests. diff, agents-md, sec-default and telemetry are the most readable templates for a mod of your own.
Which mods loaded, and why one does nothing
/plugin at the Claude Code prompt shows a dim line under the tabs with the count and the names, such as 1 mod active · first-mod. If your mod isn’t named there, its hooks module didn’t load.
When a module or one of its hooks fails, Claude Code skips it and the session continues, so a broken mod looks like one that does nothing. Two steps:
- Run
claude plugin validate ./first-modin your shell. It catches a misspelled event, a bad manifest and a module Claude Code can’t read, without starting a session. - Read the line Claude Code writes when it skips something. Where it lands depends on the session: a dim line in the transcript in a session with hot reloading, the debug log only in any other interactive session (
claude --debug), and stderr in aclaude -prun with--plugin-dir.
The line starts with hooks module, the mod’s name and not loaded:. The reason follows, for example another plugin of that name loads first: another enabled plugin has the same name and holds it. If it reads hooks module did not load: with a file and a line, the error is in your code.
Turn mods off
- One mod: disable or uninstall its plugin from the Installed tab in
/plugin. - All of them, for one session:
claude --safe-mode. It also disables your other customizations. - Every mod you installed, in every session: set
"disableAllHooks": truein~/.claude/settings.json. Your settings hooks and your custom status line stop too. What your organization manages keeps running.
disableAllHooks and your organization’s allowManagedModsOnly stop the mod and leave the rest of its plugin in place: it stays installed, and its skills, commands, agents and MCP servers load. None of these settings stop the built-in mods, and neither do --bare and --safe-mode.
Limits
- Drawing happens in the terminal and the Code tab of the Desktop app only. In the VS Code extension’s chat panel, in
claude -p, in the Agent SDK and in a cloud session the hooks run, but nothing shows. - A WSL session in the Desktop app has no plugins, so it has no mods either.
- No sandbox, and no way to change the permission prompt.
- A file in a hooks module can’t nest scopes, meaning functions, blocks and loops, more than 2,000 deep, or the module won’t load.
- Your organization can use
allowManagedModsOnlyto allow only its own mods.claude plugin testdoesn’t report that; you find out when Claude Code refuses a mod you installed.
Changes
- 2026-10-13: First version, checked sentence by sentence against the docs of 2026-10-13.
Sources
- Mods overview (code.claude.com)
- Create a mod (code.claude.com)
- Troubleshoot a mod (code.claude.com)