Text of code.claude.com › docs › en › plugins › mods › overview as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Mods overview - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. A mod is a plugin that changes how Claude Code looks and behaves. It’s made of JavaScript or TypeScript event handlers: Claude Code calls one when an event happens, such as a tool call, a submitted prompt, or a part of the interface being drawn, and the handler can watch the event, change it, or take it over.

Use a mod to add a feature of your own to Claude Code, such as a pane that charts how full your context is after each request. For the files in a mod and a complete example, see How a mod works . Claude Code’s existing hooks also run on events, as a shell command, HTTP request, or prompt you configure in a settings file. A mod’s handlers are functions that run inside Claude Code instead. Claude Code calls both kinds hooks: on these pages, “hook” means a mod’s handler, and the settings-file kind is a “settings hook”.

What a mod can do Settings hooks, skills, status lines, and MCP servers work from outside Claude Code: each one runs a script, or gives Claude text or tools. A mod runs inside Claude Code, so it can do things they can’t: Draw an interface you can use : a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields. See Draw in the interface . Redraw Claude Code’s own interface : replace or restyle parts Claude Code draws itself, such as a tool call’s row, the spinner, or the dialog Claude asks questions in.

See Change what Claude Code already draws . Step into a tool call or a request : for example, hold a tool call while you ask the user a question, answer it without running the tool, or send one request to a different model. See Guard or change a tool call and Follow a turn . Run your own code on a command : a /command that runs your function at once, with no Claude turn, even while Claude is working. See Add a command or a tool .

Share data between hooks : a mod’s hooks share the variables in its file, so what one hook records, another can show. For example, one hook can count tool calls while another shows the count beside the spinner, or one can read each request’s token usage while another charts it in a pane. See React to events . Mods work in the Claude Code CLI, the Code tab of the Claude Desktop app, and the VS Code extension. See Where mods run for how they behave elsewhere, such as in claude -p and cloud sessions.

If a settings hook, a skill, or an MCP server already does what you need, compare them before you write a mod. To manage mods for an organization, see Manage mods for your organization . Get a mod To start with a mod: Use one you already have : some of Claude Code’s own features are mods, such as /diff . See Mods built into Claude Code . Make one : describe what you want in a Claude Code session, and Claude writes the mod.

See Ask Claude for a mod . To learn how a mod’s code works, write one yourself . Install one : see Install or update a mod , or try a sample mod Install or update a mod A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests. Install mods only from authors and marketplaces you trust. See Decide whether to trust a mod . A mod installs as a plugin, from a marketplace.

Give the plugin’s name, an @ , and the marketplace’s name. These examples install a plugin named token-chart from a marketplace named your-org : In a Claude Code session, run /plugin install token-chart@your-org . In your shell, run claude plugin install token-chart@your-org . Install plugins covers marketplaces, scopes, the VS Code extension and the Desktop app, and keeping plugins updated , all of which apply to a plugin that contains a mod without changes.

If you install or update a mod from your shell while a session is open, run /reload-plugins in that session to load it. Otherwise it loads the next time you start Claude Code. Try a sample mod Anthropic shares sample mods in the claude-code/mods directory of the claude-code-playground repository . Each one is a complete plugin, and its README says how it was built. The repository shares them as they are, without support. 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 buttons to proceed or cancel replay-theater : adds a /replay command that steps through the file edits Claude made in the last turn A sample mod runs with your permissions.

To see what one does before you load it, list its hooks and calls . To try one, clone the repository and load the mod’s directory for one session with --plugin-dir . To confirm the mod loaded, check which mods the session loaded . To keep one, add the clone’s claude-code/mods directory as a marketplace , then install the mod from claude-code-playground-mods . The marketplace points at your clone, so the mod stops loading if you move or delete it.

Decide whether to trust a mod A mod is code that runs with your permissions, inside Claude Code. Install mods only from authors and marketplaces you trust . What a mod can reach A mod runs with your permissions, so before you install one, know what it has access to. Once it loads, a mod can: Act on your machine as you : read and write files anywhere your user account can, start programs, and make network requests Read your secrets : environment variables and settings files, including an API key you keep in either See your session : every prompt you send and every tool call Claude makes Change your session : rewrite a prompt or a tool call, submit a prompt as if you had typed it, or send a message to another of your sessions Act without asking you : approve a tool call before you’re asked Spend your usage : call a model on your plan or API key Mods aren’t sandboxed.

If you turn on sandboxing , the sandbox isolates the Bash commands Claude runs, and a process that a mod starts runs outside it. A mod can approve many tool calls that your deny or ask rules or your PreToolUse hooks would stop, unless the built-in guard prevents it. With the guard loaded, by default a user’s mod can’t do this. In a local terminal session, cc-plugin-sec-default on the Installed tab of /plugin means the guard is loaded.

A mod can restyle much of Claude Code’s interface, but not the permission prompt. It can’t change what a prompt shows you. List what a mod does before you install one Before you install a mod, you can list which events it handles and what it asks Claude Code to do, such as read a file or make a network request, without running it. Get the plugin’s files first, for example by cloning its repository. Then, in your shell, run claude plugin validate on the plugin’s directory: claude plugin validate ./some-mod The hooks: and calls: lines in the output list the events the mod handles and what it asks Claude Code to do.

Review what a mod can do shows the output and which calls to look for. Turn mods on or off Mods are on by default. In the terminal, use Claude Code v2.1.287 or later. The Desktop app includes its own copy of Claude Code, and mods work there from v2.1.286. Check the version in the place you use mods: Terminal : in your shell, run claude --version . If yours is older, update Claude Code . Desktop app : in a local session in the Code tab, enter /status and read the Claude Code row, which shows a version such as 2.1.286 .

If yours is older, update the Desktop app . To turn mods off, choose how many to stop, and for how long. To turn them back on, undo the same change: One mod : disable or uninstall its plugin from the Installed tab in /plugin Every installed mod, for one session : start Claude Code with --safe-mode , which also disables your other customizations Every mod you install

The rest of this page is on the live site.