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
Claude Mods are early access. Anthropic says the API a mod is written against may change between releases without notice, and hooks modules load only where function hooks are enabled. This site is unofficial: the sources are linked beside each idea and in the 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 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.
Anthropic ships four mods inside Claude Code and publishes their source. Read them in the directory, in the Mods README (opens in a new tab), or in the announcement issue (opens in a new tab).
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 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. A mod is the only one that hooks the engine's own events as functions.
| Kind | What it is | How you write it | What it can do | Source |
|---|---|---|---|---|
| Mod | A plugin whose behaviour lives in a hooks module. | TypeScript functions shaped ($, e, next), registered with on(event, hook) in one register entry. | Hooks the engine's own events: refuse or answer a tool call, add commands, draw interface elements. Early access. | Mods README (opens in a new tab) |
| Plugin | A self-contained directory that packages other extensions so they can be shared. | A .claude-plugin/plugin.json manifest beside skills, agents, hooks or MCP servers. | Bundles those pieces so a team can install and version them together. A mod is a plugin. | Plugins docs (opens in a new tab) |
| Classic hook | A handler that Claude Code runs at a lifecycle event such as PreToolUse. | A shell command, HTTP endpoint, MCP tool call, prompt or subagent, set up in configuration. | Receives JSON about the event and can block some of them: exit code 2 blocks a tool call at PreToolUse. | Hooks docs (opens in a new tab) |
| MCP server | An external tool or data source that Claude Code connects to over the Model Context Protocol. | Any program that speaks MCP, added with claude mcp add. | Gives Claude tools to call, such as an issue tracker, a database or an API. | MCP docs (opens in a new tab) |
| Skill or slash command | Instructions that Claude loads when they are relevant, or that you run as /skill-name. | A SKILL.md file with instructions, in a folder that can hold supporting files. | Teaches Claude a procedure. Its body loads only when used. Custom commands in .claude/commands have been merged into skills. | Skills docs (opens in a new tab) |
What a mod can hook
Function hooks name 125 events: 38 engine events, 54 calls on $ and 33 classic hooks bridged in as classic.<Name>. The names were read from Anthropic's type declarations at commit a92ea1c (Claude Code 2.1.277) on 2026-09-21. 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 TypeScript functions shaped ($, e, next). Anthropic ships four mods inside Claude Code itself and publishes their source.
Are Claude Mods ready to use?
They are early access. Anthropic says the API a mod is written against may change between releases without notice, and a mod's hooks module loads only where function hooks are enabled.
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 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.