Claude Mods: how to use them (install, create, safety)

Quick answer: what are Claude Mods?

Claude Mods are Claude Code plugins made of event handlers. When Claude Code does something (calls a tool, gets a prompt, draws the spinner), it runs your mod functions. A mod can observe an event, rewrite it, take it over, add panes/buttons, or add /commands. Some built-in features (for example /diff) already ship as mods.

Mods run with the same permissions you have on the machine. They are not sandboxed. Install only from sources you trust.

Requirements: version and where they run

• Terminal: Claude Code v2.1.287 or newer (claude --version). Mods are on by default.
• Desktop: Code tab, from about 2.1.286; check with /status.
• Drawn UI (pane, band): terminal and Desktop. In the VS Code extension, claude -p, or cloud, hooks may run but UI drawing is limited or absent.
• WSL in Desktop: plugins (and therefore mods) are not available in WSL sessions.

What a Claude Mod can do

• Draw UI: a pane beside the transcript, a band above the prompt, buttons, inputs
• Restyle existing UI: tool-call rows, spinner, dialogs
• Step into tool calls and turns: block, rewrite, or redirect
• Add /commands that run your function immediately, with no Claude turn
• Share state across hooks (counts, usage, history in $.state)

How to install Claude Mods

A mod installs as a plugin from a marketplace. Pattern: plugin-name@marketplace-name.

• In a session: /plugin install token-chart@your-org (docs example)
• From the shell: claude plugin install token-chart@your-org
• If a session was already open when you installed from the shell: /reload-plugins
• Check: /plugin shows a dim line like "1 mod active · mod-name"
• Before install: claude plugin validate ./path-to-mod for hooks: and calls: lists

How to create a Claude Mod (quick manual)

• Start claude and describe what you want ("a band that shows how many tool calls this turn has").
• Optional: /plugin-authoring to load the built-in mod-writing skill.
• Allow hot reload when asked. A mod Claude writes lives in that session and may be cleaned up after cleanupPeriodDays.
• To keep it: copy the folder somewhere (for example ~/mods/...), then load it as a plugin or local marketplace.
• No Node/bundler needed: Claude Code loads .js/.ts directly. Typical layout: plugin.json, hooks/hooks.json, hooks/register.js.

In register.js you export register(on) and register events with on('tool.call', ...) or on('ui.render', ...). The hook can call next(e), next(modifiedEvent), or answer the event itself.

Safety: what to check

• Can read/write files, start programs, make network requests
• Can read env vars, settings, and API keys stored there
• Sees prompts and tool calls in the session; can approve tool calls without a dialog
• Can spend usage on your plan or API key
• Bash sandboxing does not isolate processes a mod starts

How to turn them off

• One mod: disable/uninstall in /plugin → Installed
• All installed mods, one session: claude --safe-mode
• All installed mods, permanently: "disableAllHooks": true in ~/.claude/settings.json (also stops settings hooks / custom status line)
• Early-access CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: remove it; from 2.1.287 it is ignored

Claude Mods vs hooks, skills, and MCP

• Mod: functions inside the Claude Code process; can draw UI and rewrite events
• Settings hook: script/HTTP/prompt from settings; good for allow/deny/log, no UI
• Skill: SKILL.md instructions Claude reads
• MCP: external server that gives Claude tools for outside systems

Pick a mod when you want a pane, band, custom command, or event rewrite. If you already have a policy script, a settings hook is often enough.

Practical Claude Mods examples

• token-weather (Anthropic sample): context-window forecast above the prompt
• blast-radius: holds risky commands (rm -rf, force push) and asks for confirmation
• replay-theater: /replay for file edits from the last turn
• Tool-call counters beside the spinner (docs example)
• Team policy: admins can limit which mods load in an organization

Conclusion

Claude Mods are the official way to customize Claude Code from the inside: UI, tool calls, commands. Update to 2.1.287+, install only from verified sources, validate before you trust, and keep Claude-written mods if they earn a place. At Athryx Tech we use Claude Code on real projects; if you want a team workflow (mods, skills, MCP) for product development, tell us what you want to automate.