What Are Claude Code Mods? Anthropic's New Plugin Feature

Claude Code mods are a new way to customize Anthropic's terminal coding agent: small JavaScript or TypeScript functions, packaged as plugins, that hook into the events Claude Code already fires — a tool call, a submitted prompt, a part of the screen being drawn — and can watch, rewrite, or take over what happens next. Anthropic announced mods on October 1, 2026, and documented them in full at code.claude.com. Unlike a settings-file hook or a slash command, a mod runs inside Claude Code's own process, which means it can draw panes, buttons, and text fields in the interface — not just block or log an action from the outside.

What exactly is a Claude Code mod?

According to Anthropic's documentation, a mod is "a plugin that changes how Claude Code looks and behaves," built from JavaScript or TypeScript event handlers. Claude Code already fires an event every time it does something meaningful: calling a tool, asking for permission, drawing a spinner, rendering a dialog. A mod registers a function against one of these events, and Claude Code calls that function when the event happens. The handler can let the event continue unchanged, rewrite it, or answer it itself so Claude Code's usual behavior never runs.

Technically, a mod is just a plugin with a hooks module attached. A minimal mod has three files: a plugin.json manifest (the same manifest any Claude Code plugin uses), a hooks.json file that points to the code, and a JavaScript or TypeScript file — commonly register.js or register.ts — that calls register(on) and wires functions to events such as tool.call or ui.render.

How mods differ from settings hooks, skills, and slash commands

Claude Code already had several ways to customize behavior before mods existed, and Anthropic's docs are explicit that these still work and still have their place. The distinction Anthropic draws is where the code runs. A settings hook is a shell command, HTTP request, or prompt configured in a JSON settings file; it runs as an external process that Claude Code calls out to. A skill is a Markdown file of instructions Claude reads into context. An MCP server is an external process that hands Claude new tools. A mod is different: its handler functions run inside Claude Code's own process, which is what lets it draw a pane, add a button, or restyle a dialog — things none of the others can do.

Anthropic's own guidance is to reach for a mod specifically "when you want a pane, a band above the prompt, a custom command, or to rewrite an event" — and to stick with a settings hook when a script you already have just needs to block, allow, or log something.

What a mod can actually do

Per the official docs, a mod's handlers can intervene in several distinct ways:

• Guard or change tool calls: hold a tool call while asking the user a question, answer it without running the tool, retry it, or redirect a request to a different model.
• Rewrite prompts: alter what Claude sees before it responds.
• Handle permissions: approve or deny a tool call before the usual prompt appears.
• Redact output: strip secrets from a tool's result before Claude reads it.
• Draw interface elements: add a pane beside the transcript, a band above the prompt box, tabs, buttons, and text fields.
• Redraw Claude Code's own UI: restyle a tool call's row, the spinner, or the dialog Claude asks questions in (though not the permission prompt itself, which a mod cannot alter).
• Add a command: register a /command that runs instantly, even while Claude is mid-turn.

Anthropic's announcement gives three concrete use cases: a pane that shows live CI/CD status as builds pass or fail, a guard that requires confirmation before a command touches production configuration, and an audit-logging mod that loads first and records every call the other installed mods make.

A worked example: a tool-call counter

Anthropic's documentation on creating a mod walks through a complete, minimal example. It shares one variable, calls, between two hooks: one that increments the count every time Claude uses a tool, and one that redraws Claude Code's spinner to show the running total — producing a status line like Thinking · tool calls: 3… while Claude works. The handlers run in the order their mods loaded, and when several mods hook the same event, the first one to load sees the event first and gets the final result last.

How a developer creates and shares a mod

There are two documented paths to a working mod. The first is to write it by hand: define the plugin manifest, point hooks.json at a code file, and write the handler functions directly, following the reference for events, elements, and the mods API. The second is to describe what you want inside a Claude Code session and let Claude write it — Anthropic says Claude Code can write the TypeScript, install it, and hot-reload it into the current session, so a developer can iterate on a mod conversationally rather than restarting Claude Code after every change.

Sharing works through the existing plugin system rather than a separate channel: a mod ships inside a plugin, and that plugin is installed and distributed exactly like any other Claude Code plugin — from a marketplace added with /plugin marketplace add, or loaded directly from a folder with --plugin-dir while developing. To publish one for others, a developer packages the mod as a plugin and submits it to the Claude directory, Anthropic's catalog of plugins reachable at claude.ai/directory. Anthropic also publishes a small set of sample mods developers can clone and study directly, including a context-window forecast pane and a guard that previews what a risky shell command like rm -rf would change, in the claude-code-playground repository on GitHub.

Before installing someone else's mod, Claude Code offers a review step: running claude plugin validate against a cloned plugin directory lists the events it hooks and the calls it makes — reading a file, making a network request — without actually running it, a check described in Anthropic's plugin security guidance.

Mods are not sandboxed

Anthropic is direct about the risk: a mod is code that runs with the installing user's own permissions, inside Claude Code. It is not sandboxed, even when Claude Code's own sandboxing feature is turned on for Bash commands, because a process a mod starts runs outside that sandbox. Once loaded, a mod can read and write any file the user's account can reach, start programs, make network requests, read environment variables and API keys, see every prompt and tool call in the session, and in some configurations approve a tool call before the user is ever asked. Anthropic's guidance is to install mods only from authors and marketplaces you trust.

For organizations, Anthropic ships a built-in guard mod called sec-default, whose source is public in the mods directory of the Claude Code repository on GitHub. It loads first on Team and Enterprise plans and on machines under managed settings, and it restricts risky mod actions such as overriding a permission "deny" rule. Administrators who configure their own mods to load first are told to add sec-default back into that list so its restrictions still apply.

Some of Claude Code's own features are already mods

Anthropic has started converting pieces of Claude Code itself into mods, and says it plans to move more built-in features this way over time. Running /plugin and opening the Installed tab's Built-in section shows which ones a given session has.

Each of these can be disabled from /plugin, though a disabled built-in mod's underlying command, like /diff, falls back to Claude Code's internal version rather than disappearing.

Where mods run

Mod hooks run in effectively every way of running Claude Code, including sessions served by Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. Drawing is more limited. Interface elements render in the terminal, the Code tab of the Claude Desktop app, and the VS Code extension (from extension version 2.1.299, or 2.1.304 for providers that need feature-flag fetching). In non-interactive invocations such as claude -p, the Agent SDK, and cloud sessions at claude.ai/code, hooks still run but nothing is drawn, since there is no interface to draw into.

Why this matters: an extensibility layer, not just another hook

Settings hooks and MCP servers already let Claude Code call out to external scripts and tools. What mods add is the ability to reach into the running interface itself — the same category of move that turned a text editor into an extensible platform in products like VS Code. Instead of every team scripting around Claude Code from the outside, Anthropic is giving developers a supported way to add a pane, a status indicator, or a guardrail that lives inside the tool, package it as a plugin, and publish it to a shared directory other developers can install with one command. That is the ecosystem bet: mods turn Claude Code from a fixed CLI into a surface other developers build on top of, distributed through the same plugin and marketplace machinery Anthropic already built for skills, agents, and MCP servers. For background on what Claude Code is and how it fits alongside other agents, see Pandromeda's explainer on Claude Code, and for how it stacks up against rivals, Pandromeda has compared it with Cursor and with GitHub Copilot.

Getting started with mods

To check whether mods are available at all, a developer can run claude --version in a terminal; mods are on by default from CLI v2.1.287 and Desktop v2.1.286. From there, /plugin inside a session opens the Discover tab to browse Anthropic's official marketplace, and installing any plugin that contains a mod is the same one-line command as installing any other plugin: /plugin install mod-name@marketplace-name. To build one, Anthropic's own getting-started guide and the full mods documentation walk through the event model, the drawing API, and testing a mod without a live session.

What's next

Anthropic has said it will keep converting more of Claude Code's own built-in behavior into mods, which should make the event and drawing APIs more battle-tested as Anthropic's own team relies on them. The open question for developers is how the Claude directory fills out: whether a genuine ecosystem of third-party mods emerges the way VS Code's extension marketplace did, or whether usage stays concentrated in Anthropic's own built-ins and a handful of internal team tools. Anthropic has also flagged a public design discussion on GitHub for mods' future direction, so the API surface documented today is likely to keep evolving rather than being final. Developers building anything beyond a personal tool should watch the mods reference page for breaking changes before publishing to the directory.

Written byFelix Moreau

Felix Moreau writes Pandromeda's software coverage and how-to guides. He covers Windows, macOS and Linux updates, the apps people rely on, emulators and developer tools, and turns official documentation into clear, numbered steps that work on the current version.

More from Felix MoreauAll Software & Guides coverage