A Claude Code mod is a plugin that changes Claude Code itself: JavaScript or TypeScript functions that run inside Claude Code when something happens, such as a tool call, a submitted prompt or the interface being drawn. With them, a mod can draw its own panes beside the transcript, add its own commands, hold, rewrite or answer tool calls itself, and grant approvals. Mods have existed since version 2.1.287 of October 1, 2026; you install them like any plugin with /plugin install, or let Claude write one. The most important point is security: mods run without a sandbox, with your privileges. Without managed settings or a Team or Enterprise sign-in, a mod can even override deny rules and blocking hooks. Admins control mods through managed settings.
I work with Claude Code every day and run my team of fourteen AI employees on it. I have not yet built or tested a mod of my own. Everything here comes from Anthropic's documentation and announcement, retrieved on October 26, 2026, and the examples are Anthropic's examples, not mine. Everything about Claude is collected on my Claude page.
What a Claude Code mod is, and what it is not
Anthropic describes a mod like this: "A mod is a plugin that changes how Claude Code looks and behaves." Technically, a mod is a plugin with a so-called hooks module, a JavaScript or TypeScript file. Claude Code calls its functions when an event happens, and the function can watch the event, change it, or take it over.
The word "hook" now does double duty. The familiar hooks from settings.json, which run shell commands at fixed points, are called "settings hooks" in the mod docs; there, "hook" means a mod's function. How the building blocks differ, from Anthropic's comparison table:
A plugin is the package that can hold all of these, so a mod can ship in the same plugin as a skill and an MCP server. How plugins are structured and installed is covered in Claude Code Plugins: Install, Build, Trust. Two mix-ups to avoid: per the docs, the VS Code extension and the JetBrains plugin are not Claude Code plugins. And the status line you set up with a script in your settings is not a mod; a mod can additionally set its own status line under the prompt.
What a mod can do
Because a mod runs inside Claude Code, it can, per the docs, do things settings hooks, skills and MCP servers cannot:
- Draw its own interface: a pane beside the transcript or a band above the prompt, with tabs, buttons and text fields.
- Redraw Claude Code's own interface: for example a tool call's row, the spinner, or the dialog Claude asks questions in. A mod cannot change the permission prompt.
- Step into tool calls and requests: hold a call while asking you a question, answer it without running the tool, or send a single request to a different model.
- Add its own commands: a
/command that runs your function at once, without a Claude turn, even while Claude is working.
- Share data between functions: what one function counts, another can show, such as the number of tool calls beside the spinner.
On top of that there is an interface Anthropic calls the mods API. Through it, a mod reads and writes files, starts programs, makes network requests, reads environment variables and settings, and calls a model itself. Per the docs, those model calls use the session's credentials, so they go on your plan, your API key or your cloud provider. Every function runs under limits, for example 10 seconds of execution time per event.
Mods run in the terminal, including the JetBrains plugin, in the Code tab of the desktop app and in the VS Code extension's chat panel; a mod can draw there from version 2.1.299 of the extension, on Amazon Bedrock from 2.1.304. In claude -p, the Agent SDK and cloud sessions their functions run, but nothing is drawn. In WSL sessions of the desktop app they do not run at all.
Examples from Anthropic
All examples in this section come from Anthropic. I have not run any of them myself.
The example from the docs. A small mod consists of three files: .claude-plugin/plugin.json, hooks/hooks.json and hooks/register.js. The example from the overview page counts tool calls and shows the count beside the spinner, as in "Thinking · tool calls: 3…". This is Anthropic's code as published:
// The count, shared by the two hooks below
let calls = 0
// Claude Code calls this once when the mod loads
export function register(on) {
// Runs each time Claude is about to use a tool
on('tool.call', async ($, e, next) => {
calls += 1
// Ask Claude Code to draw the interface again, so the new count shows
$.ui.invalidate('ui.render')
// Let the tool run as usual
return next(e)
})
// Runs each time Claude Code draws the spinner
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
// Keep Claude Code's spinner, with the count added after its word
return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})
}
The first function watches every tool call and lets it through unchanged with next(e). The second rewrites an event before Claude Code draws it. The docs name a third option, "Answer": the function handles the event itself, and the usual behavior does not run.
Built-in mods. Parts of Claude Code are now mods themselves. The docs list six:
Anthropic publishes the source of diff, agents-md, sec-default and telemetry in the Claude Code repository. What AGENTS.md is about is covered in CLAUDE.md vs AGENTS.md: What Survives.
Sample mods to try. The anthropics/claude-code-playground repository holds three complete mods, shared, per Anthropic, "as they are, without support":
token-weather draws a forecast above the prompt of how full your context window is getting.blast-radius holds risky shell commands such as rm -rf, git reset --hard, a force push or a migration, shows what they would change, and offers Proceed and Cancel.replay-theater adds a /replay command that steps through the file edits from Claude's last turn one at a time.
Ideas for teams from the announcement. Anthropic names three uses: your CI/CD status in a pane beside the conversation, a confirmation before any command touches production config, and audit logging, where a mod that loads first records every call every other mod makes.
Installing, checking and turning off a mod
A mod installs like any plugin, from a marketplace: in a session with /plugin install <name>@<marketplace>, in your shell with claude plugin install <name>@<marketplace>. For a single session you load a mod folder with claude --plugin-dir ./folder without installing it. In the terminal you need version 2.1.287 or later, in the desktop app 2.1.286; mods are on by default.
Before installing, check what a mod does. The command you already know from plugins is enough:
claude plugin validate ./some-mod
Per the docs, the output has two lines that matter. hooks: lists the events the mod reacts to, calls: what it asks Claude Code to do. The admin docs single out $.fs.read and $.fs.write (read and write files anywhere you can), $.process.run (start programs as you), $.http.fetch (network requests), $.env.get and $.settings.read (environment variables and settings, which can hold keys) and $.model.complete (model calls at your cost). If tool.check is among the hooks, the mod can approve or deny tool calls before you are asked.
Which mods a session loaded is shown by /plugin in a dim line like 1 mod active · first-mod. Turning them off works at three levels: disable one mod on the "Installed" tab of /plugin, all installed mods for one session with claude --safe-mode, or all installed mods in every session with "disableAllHooks": true in ~/.claude/settings.json. The last option also stops your settings hooks and your status line; what your organization manages keeps running. Built-in mods stay on with all three; each has its own switch.
Letting Claude write a mod
The docs describe the easiest route like this: in an interactive session you say in your own words what the mod should do, for example "make a mod that shows the current git branch above the prompt". Claude uses the built-in skill plugin-authoring for this and writes the mod into a folder under ~/.claude/dev-mods/ followed by the session ID. In the default and acceptEdits modes, Claude Code asks for each file, because that folder is protected.
When the first file is saved, Claude Code asks whether to enable hot reloading for the session. If you agree, the mod loads at the end of the turn and reloads after every change. A mod written this way applies only to that session; to keep it, copy the folder somewhere of your own and load it with --plugin-dir, or put it in a marketplace. Per the docs, a mod Claude writes does not load in three cases: when nobody can approve it, as in claude -p or dontAsk mode; when you have not trusted the folder; and when mods are disabled or blocked by your organization.
If you want to write the code yourself, the docs have a tutorial for a mod that counts tool calls and adds a /tally command. According to Anthropic, you need neither Node.js nor a build step; Claude Code loads .js and .ts files directly.
Security: why a deny rule no longer always wins with mods
Anthropic says it in the announcement itself: mods "aren't sandboxed", and you should only install them from sources you trust. Per the docs, a loaded mod can act on your machine as you, read your keys from environment variables and settings, see and rewrite every prompt and every tool call, approve a call before you are asked, and spend usage on your plan. If the sandbox is on, it only wraps Claude's Bash commands; a process a mod starts runs outside it.
Whether your rules hold against a mod depends on a built-in guard mod called sec-default. It loads only when the machine has managed settings or the session runs on a Team or Enterprise /login. Five points follow:
- Without the guard, a mod can override deny rules and hook blocks. Literally: "With neither managed settings nor a Team or Enterprise
/login as the session's credential, the mod can approve a call that a deny rule refuses or a PreToolUse hook blocked." That applies to Pro and Max without managed settings, to API keys, and to Bedrock, Google Cloud and Microsoft Foundry without managed settings. A session on a long-lived CLAUDE_CODE_OAUTH_TOKEN does not count as a Team or Enterprise login either.
- Even with the guard, your rules only cover Claude's tool calls. "With
Read(.env) denied, a mod can still read that file with $.fs.read or start a program that does." A deny rule for WebFetch or CLAUDE_CODE_DISABLE_WEB_FETCH does not stop a mod's network requests. Only when your organization's policy does not allow WebFetch at all does Claude Code also refuse every $.http.fetch request from a mod. No network switch covers programs a mod starts with $.process.run.
- In
auto mode the classifier is skipped. Per the docs, a call a mod approves is not checked by the classifier, even with the guard. The exception: the session runs with --permission-prompt-tool or an Agent SDK canUseTool callback. Since version 2.1.283, auto is the starting mode in the terminal and VS Code, so this affects every such session in which you do not pick another mode.
- An organization's own guard mod is not a hard boundary. "A session can run without your mod." If the thread that runs installed mods crashes three times, Claude Code unloads every mod that is not built in, and with
--safe-mode a session starts without installed mods, the organization's included.
- The precedence can be switched off. With the option
allowModsToOverrideDenyRules, a user's mod may also approve calls a deny rule refuses. That is a deliberate admin decision, not a default.
With the guard, ask rules and blocking PreToolUse hooks also stay in force, and a user's mod cannot change what managed hooks receive or decide, nor the system prompt, managed instructions or the tools of managed MCP servers. How deny rules, sandbox and hooks work together is in Claude Code Security: Permissions and Sandbox, and how settings hooks work in detail is in my article on hooks.
Mods in a team: what admins set
For organizations, Anthropic has a dedicated admin page. Managed settings come as a file, through device management or from the claude.ai admin console. The main switches:
This is the smallest version that stops every user's mod from running its functions:
{
"pluginConfigs": {
"cc-plugin-sec-default@builtin": {
"options": {
"allowManagedModsOnly": true
}
}
}
}
Per the docs, users cannot undo it: the guard reads the option from managed settings only. Their settings hooks, status lines and /goal keep working. disableSideloadFlags additionally rejects --plugin-dir and --plugin-url at startup and does not load mods Claude writes during a session. How to set up a status line of your own is covered in Claude Code Statusline: Setup and Examples.
An organization's own mod only counts as such if it is loaded from a directory on the machine that managed settings name by absolute path. A plugin from GitHub, git, a URL or npm always counts as a user's mod. Anthropic's admin docs show a sample mod that refuses other mods whose code wants to start programs, and writes every tool call to the debug log. What else sets Team and Enterprise apart is in Claude Enterprise or Team: Cost and GDPR. What this means for a profession bound by confidentiality is in Claude Code Mods for Tax Firms: Uses, Risks.
Do you need a mod?
Usually not. Anthropic itself advises checking first whether a settings hook, a skill or an MCP server is enough. The rule of thumb from the docs, in my words:
- Settings hook, if you want to block, allow or log an event with a script. Examples are in my article on hooks.
- Skill, if you keep pasting the same instructions into the chat. How skills and subagents fit together is in Claude Subagents, Skills, Agents.
- MCP server, if Claude needs to reach an external system, see Set Up a Claude MCP Server.
- Mod, if you need a pane of your own, a band above the prompt, a command that runs at once, or want to rewrite an event.
The more a building block may do, the more you have to trust it. A mod may do the most.
Frequently asked questions
What is a Claude Code mod?
A plugin with JavaScript or TypeScript functions that run inside Claude Code itself. A mod can draw its own panes, add commands, rewrite tool calls and prompts, and grant approvals. Mods have existed since version 2.1.287 of October 1, 2026.
What is the difference between a mod and a hook?
A settings hook is a shell command, HTTP request or prompt from settings.json that Claude Code runs on an event. A mod runs as code inside Claude Code and can therefore do more, such as change the interface. In the mod docs, a mod's functions are called hooks too; the ones from your settings are called "settings hooks" there.
Are Claude Code mods safe?
Not by themselves. Mods run without a sandbox with your privileges, see every prompt and can read keys from environment variables. Without managed settings or a Team or Enterprise sign-in, they can even override deny rules. Check a mod with claude plugin validate first and install only from sources you trust.
How do I turn off all mods?
For one session with claude --safe-mode, permanently with "disableAllHooks": true in ~/.claude/settings.json. Both affect installed mods; the second also stops your settings hooks and your status line, while what your organization manages keeps running. Built-in mods such as AGENTS.md support are turned off one by one in /plugin.
Where can I find examples of Claude Code mods?
In Anthropic's docs, in the anthropics/claude-code-playground repository with token-weather, blast-radius and replay-theater, and in the source of the built-in mods in the Claude Code repository. Anthropic shares the sample mods without support.
Do mods run in claude -p?
Yes, per the docs their functions run in claude -p, the Agent SDK and cloud sessions, but nothing is drawn there. A mod Claude writes during a session does not load in claude -p, because nobody can approve it.
Where to go from here
Before you install a mod, check who loads the guard for you: if you work on Pro, Max or an API key without managed settings, your deny rules do not hold against a mod. Then read the mod with claude plugin validate, load it with --plugin-dir for one session first, and keep --safe-mode as your emergency exit. Per the docs, managed settings also include a managed-settings.json file in the system folder, /Library/Application Support/ClaudeCode/ on macOS and /etc/claude-code/ on Linux, and with it the guard loads even without a Team or Enterprise sign-in. I have not tried this. If you have not set up Claude Code yet, start with Install Claude Code: Windows, Mac, Linux. Where mods sit next to plugins, skills, hooks and MCP servers is in my overview of Claude Code extensions. How I build and secure my AI employees with Claude Code is what I show in my German-speaking community Claude Practitioners.
