Use the mods API - 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. The mods API is the set of methods a mod calls to act: add commands and tools, call a model, run work between events, and reach the file system, processes, and the network. Every hook receives it as its first argument, $ , with the methods grouped in namespaces such as $.ui and $.fs .
Events decide when a hook runs, and the mods API is what the hook calls once it does. Build your first mod before you start here. For every method, see mods API methods or read the types for your build . Add a command or a tool A mod can add a command for the user to run and a tool for Claude to call. Register both in a session.start hook. Claude Code waits for that hook before the first prompt, so what you register is available from the first turn.
Add a command A command is for the user. Register it, then handle command.run for its name. This example adds a /standup command that takes an optional number of days: on ( 'session.start' , async ( $ , e , next ) => { // Add /standup to the command list, with the description the user sees there await $ . command . register ({ name: 'standup' , description: 'Summarize what changed today' , argumentHint: '[days]' }) return next ( e ) }) // The matcher limits the hook to /standup, so other commands don't reach it on ( 'command.run' , { command: 'standup' }, async ( $ , e ) => { // e.args is the text typed after the command name, or an empty string return { text: 'Summary for the last ' + ( e . args || '1' ) + ' day(s): ...' } }) After the session starts, /standup appears with its description in the list you see when you type / .
The argumentHint shows in the prompt after you type the command and a space, as in /standup [days] . When you run /standup 3 , the second hook returns Summary for the last 3 day(s): ... , and the transcript shows that text after the plugin’s name. The hook never calls next , because the command has no behavior other than yours. The text you return prints in the transcript and Claude reads it, unless you hide it from Claude .
To print nothing, as a command that only opens a pane does, return {} . To let the command run while Claude is working, add immediate: true to the registration. Pick a name that no built-in command uses. Type / in a session to see them. $.command.register throws for a taken name, with a message such as "/focus" refused: it is the built-in /focus . A hook that throws is skipped, so the rest of your session.start hook doesn’t run either.
Register commands last in that hook, or wrap the call in try and catch . Hide command text from Claude To print a command’s text without Claude reading it, return { text, isTextDisplayOnly: true } from a hook that doesn’t call next , and leave immediate off the registration. Otherwise, or before v2.1.326, Claude can read the text. Add a tool A tool is for Claude. Register it with a name, a description Claude reads, and a JSON Schema for its input.
Claude sees it under a longer name made of mcp__ , your plugin’s name, two underscores, and the name you registered. You handle its calls in a tool.call hook filtered to that full name. This example, from a plugin named my-mod , registers ticket , so the full name is mcp__my-mod__ticket . It gives Claude a tool that looks up a ticket in an issue tracker: on ( 'session.start' , async ( $ , e , next ) => { await $ . tool . register ({ name: 'ticket' , // Claude decides when to call the tool from this description description: 'Look up a ticket by its id and return its title and status' , // The arguments Claude has to send: one required string named id inputSchema: { type: 'object' , properties: { id: { type: 'string' } }, required: [ 'id' ] }, }) return next ( e ) }) // The full tool name is mcp__, the plugin's name, and the registered name on ( 'tool.call' , { tool: 'mcp__my-mod__ticket' }, async ( $ , e ) => { // The tool's arguments are fields of e, so the id is e.id const response = await $ . http . fetch ( 'https://tickets.example.com/api/' + encodeURIComponent ( e . id )) // Return a result either way, so Claude learns when the lookup failed return { result: response . ok ? response . text : 'Lookup failed with status ' + response . status } }) When you ask about a ticket, Claude can call mcp__my-mod__ticket with its id.
The second hook fetches the ticket and returns the response body, which Claude reads as the tool’s result. When the server answers with an error status, Claude reads Lookup failed with status and the number. When MCP tool search defers a registered tool, Claude sees its name but not its description until it searches for it. If Claude should consider the tool on every turn, add isDeferred: false to the registration to load the full tool upfront .
The field requires Claude Code v2.1.293 or later, and earlier versions ignore it. Call a model A mod can send its own requests to a model for a small job such as classifying or summarizing text. $.model.complete sends your prompt on its own, and $.model.fork({ prompt }) sends the current conversation with your prompt at the end. This table compares what each request contains: In the request $.model.complete $.model.fork Model The model you pass The session’s model System prompt A short attribution block , then your system if you pass one The session’s system prompt Messages One user message, your prompt The conversation so far, then your prompt as a user message CLAUDE.md and other project context Not included Included, as in the conversation’s last request Tools None Claude’s tools, which the model can’t call A fork repeats the conversation’s last request, so the Claude API serves most of it from the prompt cache while the conversation is still cached.
Both calls use the session’s credentials, so they bill to the user’s plan, API key, or cloud provider. The types for your build document every $.model method. Send one prompt Pass model and prompt to $.model.complete . prompt becomes the user message. To give the model instructions, such as a role or an output format, also pass system , which becomes the system prompt. This hook answers a /triage command, registered as a command , by asking a small model to label the text typed after it: on ( 'command.run' , { command: 'triage' }, async ( $ , e ) => { const r = await $ . model . complete ({ model: 'haiku' , // The system prompt sets the job, and the prompt carries the text to label system: 'Reply with one word: bug, feature, or question.' , prompt: e . args , // One word needs few tokens, and the call gives up after 15 seconds maxTokens: 20 , timeoutMs: 15000 , }) // r.text exists only when the model answered, so check r.isAnswered first const label = r . isAnswered ? r . text . trim () : 'unknown' return { text: 'Label: ' + label } }) When you run /triage the export button does nothing , the mod sends that text to the model and prints its answer, such as Label: bug .
When the model doesn’t answer, the label is unknown . A Claude API failure doesn’t reject the call, so check r.isAnswered , and read r.reason when it’s false . The call rejects for a request Claude Code won’t send, such as a model your organization blocks. The types for your build list the other options, such as effort , and the limits give the maxTokens default. Use prompt caching $.model.complete supports the Claude API’s prompt caching .
The API caches the start of a request, called the prefix, up to a cache breakpoint that you set. When every call starts with the same long static content, such as instructions or reference material, set a breakpoint at the end of that content. Later calls then read it from the cache instead of paying the full input price for it. To set a breakpoint, pass prompt as an array of { text } blocks instead of a string, and add c
The rest of this page is on the live site.