Learn Claude Mods
What a Claude Mod is, how function hooks work, and how a mod differs from the other ways to extend Claude Code.
Note
Mods are on by default in Claude Code v2.1.287 or later in the terminal, and from v2.1.286 in the Code tab of the Desktop app. They are new, and Anthropic's docs say their events and methods can change between releases. This site is unofficial: the sources are linked beside each idea and with each table, so you can check them.
What is a Claude Mod?
A mod is a Claude Code plugin whose behaviour lives in a hooks module: one register entry that hooks the engine's events with JavaScript or TypeScript functions shaped ($, e, next). The announcement puts it this way: a mod is just a plugin that uses function hooks, and function hooks are the documented primitive that mods are built on.
Claude Code ships six built-in mods, and Anthropic publishes the source of four of them. Read those four in the directory, in the Mods README (opens in a new tab), or in the announcement issue (opens in a new tab).
Mods built into Claude Code
Some of Claude Code's own features are mods. Run /plugin and open the Installed tab to see the ones your session has, listed under Built-in. You cannot update or uninstall them, and --safe-mode, --bare and disableAllHooks do not stop them.
| Name in /plugin | What it does | Public source |
|---|---|---|
cc-plugin-agents-md | Loads AGENTS.md as project instructions. | mods/agents-md (opens in a new tab) |
cc-plugin-diff | Takes over /diff and draws its pane, in interactive terminal sessions. | mods/diff (opens in a new tab) |
cc-plugin-plugin-authoring | Gives Claude the plugin-authoring skill for writing mods. It holds a skill and no mod code. It is on unless Anthropic has turned installed mods off remotely. | Not public |
cc-plugin-sec-default | Guards what your organization manages from the mods a user installs. You cannot turn it off; an administrator sets the order in managed settings. | mods/sec-default (opens in a new tab) |
cc-plugin-telemetry | Sends the analytics records that Claude Code and its built-in mods log. | mods/telemetry (opens in a new tab) |
cc-plugin-you-should-know | Runs a side agent that watches longer tasks and shows a note above the prompt when it finds something you might miss. Disabled by default. | Not public |
Source: Mods overview (opens in a new tab), which also says how to turn each one off.
Anthropic's official docs
Anthropic documents mods in these pages. When this site and the docs disagree, trust the docs.
- Mods overview (opens in a new tab): What a mod can do, how to get one, how to turn mods off, and where they run.
- Create a mod (opens in a new tab): Ask Claude to write a mod, or write one yourself, then reload and validate it.
- Draw in the interface with a mod (opens in a new tab): Panes, the band above the prompt, buttons, text fields, and state that lasts between redraws.
- Interface gallery for mods (opens in a new tab): Every element a mod can draw, with sample code and screenshots.
- React to events with a mod (opens in a new tab): Observe, rewrite or answer tool calls, prompts and turns, and plan for other mods.
- Use the mods API (opens in a new tab): Commands, tools, model calls, timers, messages to other sessions, files and the network.
- Test a mod (opens in a new tab): Automated tests that fire events and press buttons, with no session, sign in or network.
- Troubleshoot a mod (opens in a new tab): Why a mod does nothing, what each refusal message means, and the debug log.
- Manage mods for your organization (opens in a new tab): Managed settings that stop or allow mods, how to review one, and policy mods.
- Mods reference (opens in a new tab): The full list of events, methods, render sites, elements, limits and settings.
How function hooks work
- A hook is a function
A classic hook is a handler, usually a shell command, that receives JSON about an event. A function hook is a JavaScript or TypeScript function that the engine calls with the event, so it has types and can return a value.
Source: Mods README (opens in a new tab), Announcement issue (opens in a new tab)
- The $ object
$ is the engine's own object, and the announcement says a mod's side effects are tracked over it. Each call on $ is one the engine makes, so a hook above the caller can pass it on, rewrite it, refuse it or answer it.
Source: Announcement issue (opens in a new tab), Mods README (opens in a new tab), Mods type declarations (opens in a new tab)
- next continues the chain
Hooks nest in registration order, first outermost, like Express or Koa middleware. A hook calls next(e) to run the ones beneath it, returns { deny } to refuse, or returns a value to answer on its own.
Source: Announcement issue (opens in a new tab), Mods type declarations (opens in a new tab)
- Administrators sit outermost
An administrator can remove affordances from $ so that every plugin beneath cannot use that side effect. The sec-default mod is seated outermost on a machine with managed settings or for a Team or Enterprise organization, unless managed prependPlugins says otherwise.
Source: Announcement issue (opens in a new tab), Mods README (opens in a new tab)
- Plugins can draw
The announcement says Claude Code uses React across the board, and a hook can wrap or change what a component returns. The elements a render hook draws with come from $.ui.resolve(e), not from globals.
Source: Announcement issue (opens in a new tab), Mods type declarations (opens in a new tab)
Mods compared with the rest
Claude Code can be extended in 4 other ways. They overlap, and a plugin can package several of them. Classic hooks, skills and MCP servers work from outside Claude Code: each runs a script, or gives Claude text or tools. A mod runs inside Claude Code, so it is the only one that can draw in the interface. If one of the others already does what you need, start there.
| Kind | What it is | What it can change | Draws in the interface | What you write | Pick it when | Sources |
|---|---|---|---|---|---|---|
| Mod | A plugin whose functions Claude Code calls inside its own process. | Tool calls, prompts, commands, turns, and what the interface draws. Its events and methods can change between releases. | Yes | JavaScript or TypeScript. | You want a pane, a band above the prompt, a custom command, or to rewrite an event. | Mods overview (opens in a new tab) |
| Plugin | A self-contained directory that packages other extensions so they can be shared. | What the pieces it holds can change. A mod is a plugin, and can ship beside a skill and an MCP server. | Only through a mod it holds | A .claude-plugin/plugin.json manifest beside skills, agents, hooks or MCP servers. | You want a team to install and version several pieces together. | Mods overview (opens in a new tab), Plugins docs (opens in a new tab) |
| Classic hook | A handler that Claude Code runs at a lifecycle event such as PreToolUse. The docs call it a settings hook. | Whether a tool call or prompt goes ahead, a tool call's arguments and result, and context added for Claude. | No | A shell command, HTTP endpoint, MCP tool call, prompt or subagent, set up in a settings file. | You want to block, allow or log an event with a script you already have. | Mods overview (opens in a new tab), Hooks docs (opens in a new tab) |
| MCP server | An external process or service that gives Claude tools over the Model Context Protocol. | Which tools Claude has. | No | A server in any language that speaks MCP, added with claude mcp add. | Claude needs to reach an external system, such as an issue tracker, a database or an API. | Mods overview (opens in a new tab), MCP docs (opens in a new tab) |
| Skill or slash command | Instructions that Claude reads when they are relevant, or that you run as /skill-name. Custom commands in .claude/commands have been merged into skills. | What Claude knows and does. | No | Markdown: a SKILL.md file, in a folder that can hold supporting files. | You keep pasting the same instructions into chat. | Mods overview (opens in a new tab), Skills docs (opens in a new tab) |
Where mods run
A mod's hooks run in every kind of session that loads its plugin. What it draws shows up in fewer places: only the terminal and the Code tab of the Desktop app show its panes, bands and replaced rows.
| Where you run Claude Code | Its hooks run | What it draws shows |
|---|---|---|
| claude in a terminal, an editor's integrated terminal, or the JetBrains plugin | Yes | Yes |
| The Code tab of the Desktop app, outside a WSL session | Yes | Yes, apart from the elements the mods reference marks as terminal only |
| A WSL session in the Desktop app | No, because plugins are not available in WSL sessions | No |
| The chat panel of the VS Code extension | Yes | No |
| claude -p and the Agent SDK | Yes | No |
| Remote Control from claude.ai or the mobile app | Yes, in the session on your machine | In the terminal on your machine |
| A cloud session | Yes, for a plugin that reaches the cloud session | No |
A mod that draws can check which app it is running in, and fall back to a line in the transcript or a command's text reply where nothing draws. Source: Mods overview (opens in a new tab).
What a mod can hook
Function hooks name 127 events: 39 engine events, 55 calls on $ and 33 classic hooks bridged in as classic.<Name>. The names were read from Anthropic's type declarations at commit 684800b (Claude Code 2.1.277) on 2026-10-10. The Hooks page shows which mods and plugins use which events.
Frequently asked questions
What is a Claude Mod?
A Claude Mod is a Claude Code plugin whose behaviour lives in a hooks module: one register entry that hooks the engine's events with JavaScript or TypeScript functions shaped ($, e, next). Claude Code ships six built-in mods, and Anthropic publishes the source of four of them.
Are Claude Mods ready to use?
Yes. Mods are on by default in Claude Code v2.1.287 or later in the terminal, and from v2.1.286 in the Code tab of the Desktop app. They are new, and Anthropic's docs say their events and methods can change between releases.
How is a mod different from a plugin?
A plugin is a self-contained directory that packages skills, agents, hooks or MCP servers so they can be shared. A mod is a plugin whose behaviour specifically lives in a hooks module of function hooks: every mod is a plugin, but not every plugin is a mod.
How is a mod different from a classic hook?
A classic hook is a handler, usually a shell command, HTTP endpoint, MCP tool call, prompt or subagent, that Claude Code runs at a lifecycle event such as PreToolUse and that can block some of them by exit code. A mod's function hook is a JavaScript or TypeScript function the engine calls directly with the event, so it has types and can return a value instead of just an exit code.
What events can a mod hook?
Function hooks name every engine event, every call the engine makes on $, and every classic hook, bridged in as classic.<Name>. The Hooks page shows which mods and plugins use which events.
How do I build my first mod?
Build a small mod in the Getting started guide, move a hook you already have, or watch the official video tutorials.
Where to go next
Build a small mod in the Getting started guide, move a hook you already have with classic hooks to function hooks, or watch the official video tutorials. To share a mod you have built, see how to publish it, and read what this site does and does not check and how Claude Code keeps a mod in check first.