Claude Code Mods: Install, Try and Build Your First Mod

What a mod can do

• Draw new interface: a pane beside the transcript or a band above the prompt, with tabs, buttons and text fields.
• Redraw Claude Code itself: restyle or replace parts it draws, such as a tool call’s row, the spinner or the question dialog.
• Step into a tool call or request: hold a risky command until you confirm, answer without running the tool, or send a request to a different model.
• Add instant commands: a /command that runs your function immediately, with no Claude turn.
• Share data between hooks: e.g. one hook counts tool calls while another shows the count beside the spinner.

Some of Claude Code’s own features are now built-in mods — for example /diff — which you can turn off or replace in /plugin.

Requirements

Where	Minimum version	How to check
Terminal (CLI)	v2.1.287	claude --version
Claude Desktop app (Code tab)	v2.1.286	/status in a local Code session

Mods load by default — there is nothing to switch on. Older early-access flags (CLAUDE_CODE_ENABLE_FUNCTION_HOOKS) are ignored from v2.1.287.

How to install a Claude Code mod

1. Add the mod’s marketplace (most mods publish their repository as one): in a session run /plugin marketplace add <owner>/<repo>.
2. Install the mod: /plugin install <mod-name>@<marketplace> in a session, or claude plugin install <mod-name>@<marketplace> in your shell.
3. Load it: if a session was already open, run /reload-plugins; otherwise it loads next time you start Claude Code.
4. Confirm: run /plugin — a line under the tabs lists active mods, e.g. 1 mod active · <name>.

Before installing, you can see which events a mod handles and what it asks Claude Code to do — without running it — with claude plugin validate ./<mod-folder> on a cloned copy.

Try Anthropic’s sample mods

Anthropic publishes unsupported sample mods in the claude-code/mods folder of its claude-code-playground repository:

Sample	What it does
token-weather	Draws a “forecast” of your context window above the prompt
blast-radius	Holds risky shell commands (like rm -rf or a force push), shows what they would change, with Proceed/Cancel buttons
replay-theater	Adds /replay to step through the file edits Claude made in the last turn

To try one for a single session, clone the repo and start Claude Code with --plugin-dir <path-to-mod>. To keep it, add the clone’s claude-code/mods folder as a marketplace and install from it.

Build your first mod

The fast way: describe the mod in a Claude Code session. Claude uses the built-in plugin-authoring skill (or run /plugin-authoring yourself) to write the code, load it and hot-reload it after edits.

By hand, a minimal mod is a plugin with three files:

my-mod/
├── .claude-plugin/plugin.json   # plugin manifest
└── hooks/
    ├── hooks.json               # points to your code file
    └── register.js              # the hooks module (JS or TS)

register.js exports a register(on) function. Each on('<event>', handler) call registers a hook — for example on tool.call (Claude is about to use a tool) or ui.render (part of the interface is drawn). A handler can observe the event and pass it on with next(e), rewrite it before passing it on, or answer it so the default behaviour doesn’t run. Anything beyond its own code — drawing, commands, model calls, files, network — goes through the mods API, which is why claude plugin validate can list it in advance.

Mods vs settings hooks, skills and MCP servers

	Mod	Settings hook	Skill	MCP server
What it is	Functions inside Claude Code’s process	Shell command / HTTP request / prompt on an event	SKILL.md instructions	External process giving Claude tools
Can draw in the interface	Yes	No	No	No
You write	JavaScript or TypeScript	A script + settings.json entry	Markdown	A server, any language
Pick it when	You want a pane, a command or to rewrite events	You want to block, allow or log with an existing script	You keep pasting the same instructions	Claude needs an external system

Where mods work

Hooks run in the terminal, the Desktop app’s Code tab, the VS Code extension, claude -p / Agent SDK and cloud sessions; drawn elements only appear in the terminal and the Desktop app. Plugins (and so mods) aren’t available in WSL sessions of the Desktop app.

Safety checklist before you install a mod

• A mod runs with your permissions: it can read and write your files, start programs, make network requests, read environment variables and API keys, see every prompt and tool call, and spend your model usage.
• Mods aren’t sandboxed — Claude Code’s Bash sandbox doesn’t cover processes a mod starts.
• A mod that approves tool calls can approve ones you’d normally be asked about.
• Run claude plugin validate on the source first and read the hooks: and calls: lines.
• Install only from authors and marketplaces you trust; organizations can restrict mods with managed settings.

Turning mods off: disable one in /plugin; start a session with --safe-mode to skip all of them once; or set "disableAllHooks": true in ~/.claude/settings.json to stop every mod you installed (built-in mods keep running).