Customize Claude Code with mods

Overview

On October 1, 2026, Anthropic introduced mods for Claude Code. A mod is a plugin that changes how Claude Code looks and behaves, made of JavaScript or TypeScript event handlers that run inside Claude Code. Mods let you add a feature of your own instead of waiting for it to ship. You can write a mod yourself, or ask Claude Code to write one for you.

Key features

• Observe, rewrite, or answer events

  Settings hooks run a shell command, HTTP request, or prompt from outside Claude Code, so they mostly decide whether a tool call or prompt goes ahead. A mod’s handlers are functions that run inside Claude Code, before it acts on the event, so the handler decides what happens next: observe it, rewrite it, or answer it so the usual behavior doesn’t run. The announcement’s examples include “Rewrite a prompt before it reaches the model”, block, rewrite, or retry a tool call, approve or deny a permission request, and redact secrets from tool output before Claude reads it. In the docs, “hook” means a mod’s handler, and the settings-file kind is a “settings hook”.

• Draw an interface you can use

  Settings hooks, skills, and MCP servers can’t draw in the interface. A mod can add a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields, such as a pane that charts how full your context is after each request.

• Redraw Claude Code’s own interface

  A mod can replace or restyle parts Claude Code draws itself, such as a tool call’s row, the spinner, or the dialog Claude asks questions in. The docs example counts tool calls and shows Thinking · tool calls: 3… beside the spinner. A mod can’t change the permission prompt.

• Run your own code on a command

  A mod can add a /command that runs your function at once, with no Claude turn, even while Claude is working.

• Ask Claude for a mod

  Describe what you want in a Claude Code session, and Claude writes the mod. The built-in cc-plugin-plugin-authoring plugin gives Claude the plugin-authoring skill for this.

• Ship and install as plugins

  Mods ship within plugins, so they install from a marketplace like any other plugin: /plugin install token-chart@your-org in a session, or claude plugin install token-chart@your-org in your shell. If you install a mod from your shell while a session is open, run /reload-plugins to load it.

Notes

• Requires v2.1.287 or later — Mods are on by default. Run claude --version to check. If you set CLAUDE_CODE_ENABLE_FUNCTION_HOOKS during early access, remove it; v2.1.287 and later ignore it.
• Where mods run — Hooks and drawing both work in claude in a terminal (including an editor’s integrated terminal and the JetBrains plugin) and in the Code tab of the Desktop app. In the VS Code extension’s chat panel, claude -p, the Agent SDK, and cloud sessions, hooks run but nothing the mod draws appears. WSL sessions in the Desktop app don’t load mods, because plugins aren’t available there.
• Not sandboxed — “Mods run with the same access to your machine as Claude Code itself. They aren’t sandboxed, and you should only install mods from sources you trust.” A mod can read and write files, start processes, make network requests, read API keys in environment variables, and approve a tool call before you’re asked.
• List what a mod does before you install it — Run claude plugin validate ./some-mod on the plugin’s directory. The hooks: and calls: lines in the output list the events the mod handles and what it asks Claude Code to do, without running it.
• Turning mods off — Disable one mod from the Installed tab in /plugin. Start with --safe-mode to skip every installed mod for one session, or set "disableAllHooks": true in ~/.claude/settings.json to stop them in every session (this also stops settings hooks and a custom status line).
• Organizations — Administrators decide whether mods run and which ones through managed settings. The built-in sec-default mod guards what your organization manages from the mods a user installs.
• Built-in mods — Some of Claude Code’s own features are mods, such as /diff and loading AGENTS.md; they’re listed under Built-in in the Installed tab of /plugin. The source of diff, agents-md, sec-default, and telemetry is public in the mods directory of the Claude Code repository.
• Docs — Creating, drawing, events, testing, and admin controls are covered starting from the Mods overview.