Claude Code Mods: What They Are and How to Use Them

Mods let you change how Claude Code looks and behaves with a few lines of JavaScript or TypeScript.

Last updated: 2026-10-10

What is Claude Code mods?

A mod is a Claude Code plugin made of JavaScript or TypeScript event handlers. Claude Code calls a handler when an event happens — a tool call, a submitted prompt, or part of the interface being drawn — and the handler can watch the event, change it, or take it over. Mods shipped in Claude Code v2.1.287 (released in early October 2026), and they are on by default.

Because a mod runs inside Claude Code instead of alongside it, it can do things settings hooks, skills, status lines, and MCP servers cannot: draw a pane beside the transcript or a band above the prompt with tabs, buttons, and text fields; redraw parts of Claude Code's own interface; step into a tool call or a request (hold it, answer it yourself, or route it to a different model); add a /command that runs your function directly; and share data between hooks in the same file.

Some of Claude Code's own features are already mods — for example /diff is a built-in mod that draws its own pane, and the built-in AGENTS.md loader is also a mod. Mods work in the Claude Code CLI and in the Code tab of the Claude Desktop app; hooks also run in the VS Code extension, claude -p, and cloud sessions, but custom UI only draws in the terminal and Desktop app.

How to install or build a Claude Code mod

1. Update Claude Code to v2.1.287 or later — run claude --version in your shell, or /status in the Desktop app's Code tab.
2. To install an existing mod: it installs as a plugin from a marketplace. Run /plugin install <name>@<marketplace> inside a session, or claude plugin install <name>@<marketplace> in your shell. Anthropic publishes sample mods (token-weather, blast-radius, replay-theater) in the claude-code-playground repository.
3. Review before you install: a mod runs with your permissions and is not sandboxed. Clone the plugin's files and run claude plugin validate ./some-mod — the hooks: and calls: lines list which events it handles and what it asks Claude Code to do.
4. To build your own: a minimal mod has three files — .claude-plugin/plugin.json (manifest), hooks/hooks.json (points to your code), and hooks/register.js (registers event handlers via export function register(on)). Test locally with claude --plugin-dir ./your-mod, or just describe what you want in a Claude Code session and Claude writes the mod for you.
5. Reload and verify: run /reload-plugins in an open session, then /plugin to see which mods are active.

What a mod can reach (safety)

• A mod runs with your permissions: it can read and write files anywhere your user can, start programs, and make network requests.
• It can read your secrets (environment variables and settings files, including API keys) and see every prompt and tool call in your session.
• It can change your session — rewrite a prompt or tool call, submit a prompt as if you typed it — and a mod that approves tool calls can approve ones your own rules would have blocked.
• To turn mods off: disable one plugin in /plugin, start one session with --safe-mode, or set "disableAllHooks": true in ~/.claude/settings.json to stop all installed mods everywhere.

Claude Code mods FAQ

What are Claude Code mods?
Mods are plugins made of JavaScript or TypeScript event handlers (called hooks) that run inside Claude Code. When an event happens — a tool call, a prompt, or part of the UI being drawn — Claude Code calls your handler, which can observe, rewrite, or take over the event. They were introduced in Claude Code v2.1.287 in early October 2026.

How do I install a Claude Code mod?
A mod installs as a plugin from a marketplace. In a Claude Code session run /plugin install <name>@<marketplace>, or run claude plugin install <name>@<marketplace> in your shell, then /reload-plugins if a session is open. Anthropic's sample mods live in the claude-code-playground repository and can be tried with --plugin-dir.

Are Claude Code mods safe?
Mods are code that runs with your permissions and are not sandboxed: they can read your files and secrets, see your whole session, and approve tool calls. Install only from authors and marketplaces you trust, and review a mod first with claude plugin validate, which lists its hooks and the calls it makes.

What version of Claude Code do mods need?
The terminal CLI needs v2.1.287 or later; the Claude Desktop app includes its own Claude Code with mod support from v2.1.286. Check with claude --version in the terminal or /status in the Desktop app. Mods are on by default — no opt-in flag is needed.

How are mods different from Claude Code hooks, skills, and MCP servers?
Settings hooks run an external script on lifecycle events; skills are Markdown instructions Claude reads; MCP servers give Claude external tools. Mods are functions running inside Claude Code itself — the only extension type that can draw in the interface, replace built-in features, and rewrite events mid-flight. A plugin can contain all of them at once.

Do mods work in VS Code or cloud sessions?
Hooks run in most session types, including the VS Code extension chat panel, claude -p, and cloud sessions, but a mod's custom panes and UI only draw in the terminal and the Desktop app's Code tab. WSL sessions in the Desktop app do not load plugins at all.

Related topics

• undefined — undefined
• undefined — undefined
• undefined — undefined
• undefined — undefined

Sources

• Mods overview — Claude Code Docs (official, updated 2026-10-08)
• Plugins — Claude Code Docs (official)
• Anthropic's mods let you change Claude Code's look and behavior — daily.dev (2026-10-02)
• Anthropic launches Claude Code Mods — tech coverage (2026-10-04)

This is an independent guide based on public documentation. We are not affiliated with Anthropic. Product details change — the official docs are the source of truth.