Claude Code Mods: What They Are, How to Build One

Claude Code mods are plugins that carry a JavaScript or TypeScript "hooks module": code that runs inside Claude Code and gets called on events such as a tool call, a submitted prompt or part of the screen being drawn. A mod can watch that event, change it or answer it, so it can add a pane beside the transcript, a new slash command, or a rule that holds a risky shell command until you confirm. Mods arrived in Claude Code v2.1.287 on October 1, 2026, and are on by default.

The catch: a mod is not sandboxed. It runs with your user permissions and can approve tool calls before you see a prompt. This guide covers what mods are, how they differ from hooks, skills and MCP, how to install and build one (we ran the official tutorial mod through Claude Code 2.1.301), and how to vet one. If you want agents boxed in by file and network rules, see NVIDIA OpenShell.

What are Claude Code mods?

According to Anthropic's mods overview, a mod is a plugin whose code registers event handlers, which the docs call hooks. Because it runs inside the Claude Code process rather than as an outside script, a mod can draw its own interface, restyle parts of Claude Code's, step into a tool call or model request, run a command without starting a Claude turn, and share data between its hooks.

A small mod is three files: the usual plugin manifest at .claude-plugin/plugin.json, a hooks/hooks.json file, and the code file itself. What turns an ordinary plugin into a mod is the modules key in hooks.json, which points at the code. When Claude Code loads the mod, it calls a register function exported by that file and hands it an on function. Each call to on names an event and a handler.

Every handler gets the mods API (written $), the event, and a next function, and has three choices:

• Observe: note the event and pass it on unchanged.
• Rewrite: change the event, then pass it on.
• Answer: handle it itself, so Claude Code's normal behavior never runs, for example refusing a command.

Reading a file, starting a process, calling a model or making a network request all have to go through the $ API. That is what lets Claude Code list a mod's capabilities before you install it.

Claude Code mods vs hooks, skills and MCP

The naming is confusing, because Claude Code already had "hooks": shell commands, HTTP requests or prompts set in a settings file. The docs now call those settings hooks. Here is how the four extension points split the work:

In plain terms: if you keep pasting the same instructions, write a skill (see our agent skills guide). If Claude needs to reach a database or API, build an MCP server (how to build an MCP server in Python). If a script you already have should block or log a tool call, a settings hook is enough. Reach for a mod when you need something on screen, an instant command, or deep control over prompts and tool calls. One plugin can ship all four. For ready made examples, see the Cloudflare security audit skill or the design skills for Claude Code we compared.

Where mods run

Mod hooks run in every session that loads the plugin, whichever cloud serves the model. Drawing is narrower: it appears in the terminal (including editor terminals and the JetBrains plugin), the Code tab of the Claude Desktop app, and the VS Code extension's chat panel from extension version 2.1.299. In claude -p runs and the Agent SDK, hooks run but nothing is drawn; cloud sessions run hooks only for plugins that reach them, and draw nothing. Desktop sessions under WSL don't load plugins at all.

How to install a Claude Code mod

A mod installs like any other plugin, from a marketplace: /plugin install name@marketplace in a session, or claude plugin install name@marketplace in your shell (then /reload-plugins in any open session). Anthropic's plugin install docs cover scopes and updates, and apply to mods unchanged.

To try one, Anthropic publishes three sample mods in the claude-code-playground repository, shared as is:

• 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 Proceed and Cancel buttons.
• replay theater adds a /replay command that steps through the file edits Claude made in the last turn.

Clone the repository and load one for a single session with claude --plugin-dir and the mod's folder, or add the clone's mods folder as a local marketplace to keep it. In /plugin, a dim line under the tabs then reads something like "1 mod active" with the mod's name.

You may already run mods. Several Claude Code features are built in mods, listed under Built in on the Installed tab of /plugin: AGENTS.md loading (see our AGENTS.md guide), the /diff pane, the plugin-authoring skill, a security guard, telemetry, and the opt in "You should know" side agent. Some of their source is public in the Claude Code repository's mods folder.

How to build your first mod

The fastest route is to ask, for example "make a mod that shows the current git branch above the prompt". Claude uses the built in plugin-authoring skill, writes the files into a per session folder under ~/.claude/dev-mods/, and Claude Code asks whether to enable hot reloading. That mod loads only in the session that made it and the folder is cleaned up later, so copy it out to keep it.

To learn how the code works, write one by hand. The official tutorial builds first-mod, which counts Claude's tool calls, shows the count beside the spinner and adds a /tally command. The heart of it is the hooks module:

let calls = 0
export function register(on) {
  on('session.start', async ($, e, next) => {
    await $.command.register({ name: 'tally', description: 'Show how many tool calls Claude has made' })
    return next(e)
  })
  on('tool.call', async ($, e, next) => {
    calls += 1
    $.ui.invalidate('ui.render')
    return next(e)
  })
  on('command.run', { command: 'tally' }, async () => {
    return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }
  })
  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
  })
}

Four hooks share one counter: one registers the command, one bumps the count on each tool call, one prints the total, and one appends it to the spinner. No Node.js or build step is needed; Claude Code loads .js and .ts files directly.

We ran this mod on Claude Code 2.1.301. claude plugin validate ./first-mod passed, listed the four hooks and the two API calls ($.command.register and $.ui.invalidate), and flagged the tool.call handler as a "gating hook without .catch", a nudge to add error handling. claude -p "/tally" --plugin-dir ./first-mod printed first-mod: Claude has made 0 tool calls since this mod loaded without a model turn.

Are Claude Code mods safe?

Treat a mod like any program you download. Once loaded, it can read and write files anywhere your account can, start programs, make network requests, read environment variables and settings files (API keys included), see and rewrite every prompt and tool call, and spend your usage by calling a model. Claude Code's sandboxing isolates the Bash commands Claude runs, but a process a mod starts runs outside it. A mod can approve a tool call an ask rule would have prompted for, though it can't change what the permission prompt shows.

Before installing one, clone it and run claude plugin validate on its folder. Read the calls: line closely:

• $.fs.read or $.fs.write means it touches files.
• $.process.run or $.process.spawn means it starts programs.
• $.http.fetch means it talks to the network.
• $.env.get or $.settings.read means it can read secrets.
• $.model.complete means it spends your plan or API key.
• $.prompt.submit means it can send prompts as if you typed them.

A display only mod like first-mod shows only UI and command calls. When we validated blast radius, its list included $.process.run, which fits its job of previewing a command. If the list doesn't match what the README promises, don't install it. For hard isolation, run the whole agent in a container or remote sandbox; see E2B vs Daytona vs Modal.

Turning mods off, and controls for teams

For yourself: disable one mod's plugin in /plugin, start with claude --safe-mode to skip installed mods for one session, or set disableAllHooks to true in ~/.claude/settings.json, which also stops your settings hooks and status line. Built in mods have their own switches.

For organizations, the mods admin page describes a built in guard that loads ahead of user mods on machines with managed settings or for Team and Enterprise sign ins. It stops user mods from tampering with managed hooks, instructions and MCP servers, and keeps deny rules in force. allowManagedModsOnly blocks every mod users bring, and disableSideloadFlags rejects --plugin-dir and mods Claude writes mid session.

How mods compare with other agents' plugins

Mods are specific to Claude Code, so they won't carry over to another agent. The vendor neutral Agent Plugins 1.0 standard covers only skills and MCP servers; Cursor supports it alongside its own format, which adds rules, hooks and commands, and Codex plugins bundle skills, MCP servers and hooks. The nearest relative is OpenCode 2.0, whose rebuilt plugin API includes terminal interface plugins. Still choosing an agent? See Claude Code vs Codex vs Gemini CLI.

Pros: real UI inside the agent, instant commands, fine control over prompts and tool calls, no build step, and capabilities listed up front.
Cons: no sandbox, Claude Code only, and a young API that changes often in the changelog.

FAQ

What are Claude Code mods?

Plugins with a JavaScript or TypeScript hooks module that runs inside Claude Code. Its handlers fire on events like tool calls, prompts and redraws, and can observe, rewrite or answer them.

Which version of Claude Code do I need for mods?

Version 2.1.287 or later in the terminal; the Desktop app supports them from 2.1.286. Run claude --version to check. Mods are on by default, and the early access variable CLAUDE_CODE_ENABLE_FUNCTION_HOOKS is now ignored.

What is the difference between Claude Code mods and hooks?

Settings hooks are scripts, HTTP calls or prompts run outside Claude Code on lifecycle events. Mods are functions running inside it, so they can also draw interface elements, add commands and rewrite events.

Are Claude Code mods safe to install?

Only from authors you trust. They run with your permissions and aren't sandboxed. Run claude plugin validate first and check what files, processes, network access and secrets the mod can reach.

Do Claude Code mods work in VS Code?

Yes. Hooks run in the VS Code extension, and what a mod draws appears in its chat panel from extension version 2.1.299.

How do I turn off Claude Code mods?

Disable the mod's plugin in /plugin, start a session with --safe-mode, or set disableAllHooks to true in your user settings. Built in mods have their own switches.