Claude Code mods: what they are, how to install one and how to stay safe

What are Claude Code mods?

Claude Code mods are plugins made of JavaScript or TypeScript event handlers that Claude Code calls from inside its own process, so they can change how Claude Code looks and behaves. A mod can draw a pane beside the transcript, restyle the spinner, hold a risky tool call until you click a button, or add a /command that runs your code at once with no Claude turn.

Mods shipped on by default in Claude Code v2.1.287, published on 1 October 2026, with the changelog line "Added Claude Mods: plugins may now modify deeper behavior". In the Desktop app they work from v2.1.286. They run in the CLI, the Code tab of the Desktop app and the VS Code extension.

The mods overview sums up the model: Claude Code runs your handler before it acts on an event, and the handler can do one of three things.

• Observe: note the event and let it continue unchanged.
• Rewrite: change the event before it continues, such as adding text to the spinner.
• Answer: handle the event itself, so the usual behavior does not run, such as refusing a command.

To touch anything outside its own code (files, processes, the network, a model call, drawing), a handler must call the mods API, written $ in code. That single doorway is why Claude Code can list what a mod does before you install it.

How are mods different from hooks, skills, plugins and MCP servers?

A mod is a type of plugin, so it installs and updates through the same /plugin system. What makes a plugin a mod is a modules key in its hooks/hooks.json that points to a code file. The docs compare the four extension types in a table; this is a shortened version of it:

A practical rule follows from that table. Reusable know-how (how your team reviews code, writes migrations, ships a release) belongs in a skill, because it is plain Markdown that any agent can read and nobody has to audit as code. Fixed rules that need a script belong in a settings hook. Reach for a mod only when you need to change the interface or step into an event in a way the others cannot. The skills vs plugins guide covers the packaging side, and a single plugin can ship a mod, a skill and an MCP server together.

How do you install, update or turn off a mod?

A mod installs as a plugin from a marketplace: the plugin name, an @, then the marketplace name.

# inside a Claude Code session
/plugin install token-chart@your-org

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

If you install or update from your shell while a session is open, run /reload-plugins in that session. Updates follow the normal plugin update flow, and the marketplace guide covers adding sources.

To see which mods a terminal session loaded, run /plugin. A dim line under the tabs shows something like 1 mod active · first-mod.

To turn mods off, pick the scope:

disableAllHooks stops a mod but leaves the rest of its plugin in place, so its skills, commands, agents and MCP servers still load. None of these switches stop the mods built into Claude Code, which each have their own toggle. If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it: v2.1.287 and later ignore it, so setting it to 0 does not keep mods off.

How do you check a mod is safe before installing it?

Treat a mod like any program you download. The docs list what a loaded mod can reach:

• Read and write files anywhere your account can, start programs and make network requests.
• Read environment variables and settings files, including API keys kept in either.
• See every prompt you send and every tool call Claude makes, and rewrite them.
• Approve a tool call before you are asked, in some setups.
• Call a model on your plan or API key.

Mods are not sandboxed. If you turn on Claude Code's sandbox, it isolates the Bash commands Claude runs, and a process a mod starts runs outside it. A mod also cannot restyle the permission prompt, so what a permission prompt shows you comes from Claude Code itself.

Before you install, clone the plugin and run static analysis on it without executing it:

claude plugin validate ./some-mod

The output lists the events the mod handles and every mods API method it calls:

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

Check the calls: line against what the mod claims to do. The admin page flags these as the ones to look at: $.fs.read and $.fs.write (files), $.process.run and $.process.spawn (programs), $.http.fetch (network), $.env.get and $.settings.read (secrets), $.model.complete (your usage) and $.prompt.submit (prompts sent as your own words). On the hooks: line, tool.call and prompt.submit mean the mod sees and can change every tool call and prompt. A git branch indicator that calls $.http.fetch deserves a question.

How do you make your first mod?

The quickest route is to ask Claude. In an interactive session, describe it, for example "make a mod that shows the current git branch above the prompt". Claude uses the built-in plugin-authoring skill (you can load it yourself with /plugin-authoring) and writes the mod under ~/.claude/dev-mods/<session-id>/. When it saves the first file, Claude Code asks whether to enable hot reloading for the session. Choose Enable for this session and the mod loads at the end of the turn. A mod Claude writes loads only in that session, so copy its folder somewhere like ~/mods/git-branch and start later sessions with claude --plugin-dir ~/mods/git-branch.

To write one by hand, the create guide builds a three-file plugin:

first-mod/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.js

hooks.json points at the code:

{
  "description": "The first-mod hooks module",
  "modules": ["./register.js"]
}

And register.js exports a register function that receives on. This version, adapted from the overview's example with the comments removed, counts tool calls and shows the count beside the spinner:

let calls = 0

export function register(on) {
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })

  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

Load it with claude --plugin-dir ./first-mod. No Node.js, bundler or build step is needed, because Claude Code loads .js and .ts files directly, and it hot-reloads the module when you save. Three habits help:

• Run claude plugin validate ./first-mod after each change. Write event names as string literals, since validation fails otherwise, and write every file as an ES module with import, not require.
• Read the TypeScript declarations Claude Code writes into .claude-plugin/types/. The docs say to trust these over any page when they disagree, because events and methods can change between releases.
• Write tests and run them with claude plugin test, which needs no session, sign-in or network.

Which mods are built in, and which samples can you try?

Some Claude Code features are already mods. Run /plugin, open Installed and look under Built-in: cc-plugin-agents-md loads AGENTS.md, cc-plugin-diff draws the /diff pane, cc-plugin-plugin-authoring provides the authoring skill, cc-plugin-telemetry sends analytics, cc-plugin-sec-default guards what your organization manages, and cc-plugin-you-should-know (off by default) shows notes from a side agent above the prompt. Anthropic publishes the source of several of them in the mods folder of the claude-code repo.

For ideas, Anthropic shares three unsupported samples in claude-code-playground:

• token-weather draws a forecast of your context window above the prompt.
• blast-radius holds a risky shell command, such as rm -rf or a force push, and shows what it would change, with buttons to proceed or cancel.
• replay-theater adds a /replay command that steps through the file edits Claude made in the last turn.

Clone the repo and load one with --plugin-dir to try it. Run claude plugin validate on it first, since samples run with your permissions too.

How do organizations control which mods load?

Administrators use managed settings. To stop every user-installed mod from running its hooks while leaving settings hooks, status lines and /goal working, set the allowManagedModsOnly option on the built-in guard:

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

Users cannot undo it from their own settings files or --settings. The wider allowManagedHooksOnly setting also blocks hooks in users' own settings files. Plugin controls such as strictKnownMarketplaces still decide whether a mod's plugin can be installed at all. The enterprise guide covers managed settings delivery.

Where do mods fit in a library of skills and prompts?

Mods are the right tool for interface and event changes, but most of what teams reuse is instructions. Kipt keeps prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Claude Code with one npx skills add command. Keep the know-how there as skills, and keep the few mods you trust in a plugin marketplace your team controls.

Sources: Mods overview, Create a mod, Manage mods for your organization and the Claude Code changelog.