Text of code.claude.com › docs › en › plugins › mods › reference as Styx crawled it on Nov 19, 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 reference - 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. Look up any event a mod can handle, mods API method it can call, or render site it can draw in. Entries cover the Claude Code CLI and the Desktop app as of v2.1.290, and the VS Code extension as of v2.1.299.

Each entry gives the name and a one-line description, and links to the guide section that explains it where there is one. The complete reference is Claude Code’s TypeScript declarations for mods , which describe every event, method, and element, with examples. The copy on GitHub can be older than the Claude Code version you have installed. When the two disagree, trust the copy Claude Code writes for your version . Files A mod is a plugin directory with these files: File Required Contents .claude-plugin/plugin.json Yes The plugin manifest .

Mods add no required fields. hooks/hooks.json Yes modules : an array with one path, relative to this file, to the hooks module, as in "modules": ["./register.js"] . Can also hold settings hooks under hooks . The hooks module, such as hooks/register.js Yes The mod’s entry point. Exports register(on, options) . Named .js , .mjs , .cjs , .jsx , .ts , .mts , .cts , or .tsx . An ES module. types/index.d.ts , unless types in the manifest names another path When the mod uses $.state or adds a namespace to the mods API Declares PluginState values and any namespace the mod adds.

To leave types out of the manifest, you need v2.1.299 or later. Files whose names end in .test.ts or .test.tsx No Tests that claude plugin test runs register receives on and options . options holds the values of the userConfig fields the manifest declares, with defaults filled in. The hook function A mod registers each of its hooks, which are event handlers, by calling on inside register . on takes the event’s name, an optional matcher , which is a filter on the event’s fields, and the hook, as in on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)) . on returns a registration with one method, .catch(handler) , which sets the hook’s error handler .

Argument What it is $ The mods API: every method in mods API methods . Write each call in full, namespace then method, as in $.fs.read('notes.md') . e The event’s input, as deeply frozen plain data. To change it, pass a copy to next . next(e) The next handler, as in middleware. Runs the hooks after this one, then Claude Code’s behavior. Resolves to the event’s result. next.signal An AbortSignal that aborts when the event is abandoned next.origin { plugin, tier } of whoever fired the event.

Claude Code itself is { plugin: 'engine', tier: 'core' } . A mod’s tier is its priority group in the order mods run in : prepend , user , append , or builtin . next.budget The hook’s time limit in milliseconds: next.budget.ms is the whole limit, and next.budget.remainingMs is what’s left now next.to(e, tier) Skips to a later tier, which is append , builtin , or core . next.to(e, 'append') skips the mods a user installed.

Only a mod in prependPlugins or appendPlugins can call it. next.error In a .catch handler only. kind is throw or timeout , and message is the error’s text. next.called In a .catch handler only. true when the hook had called next . Events Events are grouped by what they concern, each with when it fires and what a hook on it can return. Hooks on turn.step and process.spawn are async generators, and other hooks are async functions.

The last column of each table uses shorthand. next(e) passes the event on unchanged. next({ ...e, text }) passes on a copy with the named field changed, as in next({ ...e, text: e.text.trim() }) . An object answers the event without calling next , and a word such as reason stands for a string you write, as in { deny: 'Use the file tools.' } . Tools Tool events fire around each tool call Claude makes, from the description Claude reads to the decision on whether the call runs: Event Fires when A hook can return tool.call A tool is about to run next(e) , { deny: reason } , or { result } tool.check Claude Code decides whether a tool call may run, after the tool.call and PreToolUse hooks. next(e) resolves to the decision the rules, the permission mode, and those hooks reached. next(e) or { decision } , with decision set to allow , ask , or deny and an optional reason tool.describe Once for each tool, when its description is first sent to Claude.

A second time for an MCP tool when Claude loads it through tool search , with e.description set to the text Claude reads for the loaded tool. { description } , optionally with isDeferred set to true to put the tool behind tool search or false to load it upfront. Add breakPromptCache: true to send a changed description on the next turn. Agent and organization fields on tool.check In a tool.check hook, read these fields to tell a subagent’s call from the main conversation’s, and to see whether your organization requires approval for a connector tool: e.agentId : set when a subagent or an in-process teammate makes the call, and absent when the main conversation does e.ceiling : ask for a connector tool your organization set to ask , in sessions where that setting reaches Claude Code On tool.check , e.agentId and e.ceiling require Claude Code v2.1.290 or later.

The e.isReadOnly field on tool.check In a tool.check hook, e.isReadOnly is true when the tool reports this call as read-only. Otherwise the field is absent, not false . The value is the tool’s own report, so read Check whether a tool call is read-only before you approve a call on this field alone. On tool.check , e.isReadOnly requires Claude Code v2.1.304 or later. Prompts and what Claude reads Prompt events cover the text the user types and the text Claude Code sends to Claude on its own, such as the system prompt and reminders: Event Fires when A hook can return prompt.submit A prompt is submitted next({ ...e, text }) , next({ ...e, context }) , or { drop: reason } prompt.fill , prompt.suggest Text is about to go into the prompt box as a draft, or as a dim suggestion next(e) with changed text prompt.edit The user edits the prompt box next(e) prompt.autocomplete The user types in the prompt box and a word ends at the cursor. e.token is that word.

Claude Code doesn’t wait for the hook: its own autocomplete rows show first. { suggestions } , a list of { text, label, description } rows shown below Claude Code’s own. Choosing a row writes its text over the word. prompt.compose Claude Code renders a system prompt { sections } , a list of { id, text, scope } in the order they’re sent prompt.section Once for each named section of the system prompt. e.name is the section’s id in prompt.compose . { text } , or { text: null } to omit the section.

Add breakPromptCache: true to send a changed section on the next turn. prompt.context Once for each conversation, for the context sent with the first message { blocks } prompt.attachment Claude Code adds a message of its own for Claude, such as a reminder. e.type names the kind, and for the kinds the types declare, e.detail holds the facts the text was written from. { text } , or { text: null } to omit it prompt.mention Claude Code is about to read a file that a prompt @-mentions.

Requires Claude Code v2.1.290 or later. next({ ...e, path }) to read a different file, or { deny: reason } skill.prompt A skill’s text is expanded for Claude { text } attribution.text Claude Code composes commit or pull request attribution text { text } Source and frontmatter fields on skill.prompt In a skill.prompt hook, you can read these fields along with the skill’s name in e.skill and the text Claude reads in e.text : Field Type What it holds e.source string Who provides the skill: policySettings , userSettings , or projectSettings for a skill in the enterprise, personal, or proje

The rest of this page is on the live site.