Follow Discord
Sweep 06 Nov 2026 · 01:32Z Build v2.1.319 537 read Stable v2.1.311 Latest v2.1.318 Next v2.1.319 Feeds RSS JSON llms.txt llms-full.txt Unofficial
Home / Reference / Mods Guide
Mods API

The whole surface.

Every noun, verb, event and type a Claude Code mod can reach, with the signature and the doc comment Claude Code wrote for it. Anthropic's Mods reference covers the same surface a table at a time. This is every declaration in full, and none of it is written by hand here: the release pipeline pulls the declarations out of the shipped binary and this section renders what it found.

Search to find a name. The three pages under it are the same symbols in full, with the source text.

Symbols866every one, in the index below
Mined from2.1.319the shipped binary
Machine readableapi.jsonin pages, sized for an agent's fetch; api-full.json is the whole document
What changed

v2.1.319

+9 added · 4 removed · 3 changed · 3 docs only 5 may break Every release since v2.1.259
  1. EventsEvery event a hook can be registered for, with the payload it arrives with and the result it may return.
  2. clock.every event The argument of $.clock.every(ms, fn), dispatched once per period: fn runs each time a dispatch resolves, and the next period is asked.
  3. process.spawn event The argument of $.process.spawn(request): the request itself.
  4. settings.read event The argument of $.settings.read({ source }), and the layers the read is made of, which the engine fills; rewritable, deniable.
  5. TypesEvery declaration in the file, verbatim, with the doc comment above it.
  6. AgentCallRecord type What an Agent call a plugin raised ($.tool.call({ tool: "Agent", ... })) answers as result once the agent settles; text is its final answer.
  7. AgentInfo type One agent loop of this session as $.agent.list() returns it: a subagent or a teammate.
  8. AgentLoop type Which model loop an event happened in: the loop's agent id inside a subagent's or a teammate's loop, absent on the main loop.
  9. AgentOfferInput type The input of agent.offer: one agent type, at the moment the engine offers it to the model.
  10. AgentOfferResult type What an agent.offer hook returns: whether the model is offered the agent type, in its listing and at dispatch.
  11. AgentSpawnArgs type agent.spawn's input as the call takes it: what the Agent tool's caller says; the engine fills the rest.
  12. AgentSpawnInput type The input of agent.spawn: what is decided about an agent about to start, before its model is resolved.
  13. AgentSpawnResult type What an agent.spawn hook returns and what next(e) resolves to: the started subagent's { model, agentId }, or { deny: reason }, refusing it.
  14. AgentSpec type What $.agent.register takes: an agent type this plugin defines, spelled as an agent definition in settings JSON is, plus its name.
  15. AgentStatus type Where an agent's loop stands: pending (not started), running a turn, waiting (held), idle (between turns, until a message wakes it), or ended.
  16. AgentTeammateRecord type What an Agent call that started a teammate answers as result at tool.call: the started teammate's two ids, its name and its model.
  17. AnyEventHook type The hook on("*", hook) takes: it runs on every event, plugin nouns no declaration names included, so e is unknown and next is StarNext.
  18. AnyKeyOf type Every key of every variant, index signatures included.
  19. ApiContentBlock type One content block of an ApiMessage: type names its kind (text, tool_use, tool_result, image, document, thinking, ...).
  20. ApiMessage type One message of the conversation in Messages API form, as $.session.messages({ as: "api" }) returns it.
  21. Args type The argument of event N: e in its hooks, and what its call takes. For a union of names, the union of their arguments.
  22. AskOptions type Options of $.ui.ask.
  23. Atom type A named value with its initial, as atom(ref, initial) makes it: read, it is never undefined; while nothing is written it reads as the initial.
  24. AtomFunction type atom(ref, initial): a named value with its initial, so a read is never undefined; given { shape }, for a key declared Shaped<T>.
  25. AtomOptions type The options of atom: shape, a tag the value is kept under, so a reload of the plugin's code that names another tag finds the value absent.
  26. AttributionTextInput type The input of attribution.text: one text the engine asks the model to write into a commit or a pull request, at the moment it is composed.
  27. AttributionTextKind type Which git text attribution.text carries: the commit trailer, the PR footer, the mandate's or the commit gate's sentence naming the exemption.
  28. AttributionTextResult type What an attribution.text hook returns: the text the model reads in that place.
  29. AudioClip type What $.audio.play plays: a URL the engine fetches, or the bytes.
  30. BackgroundTaskSummary type
  31. BaseHookInput type
  32. BoxHoverProps type The Box props a hover may override, none of which moves the Box's siblings, and scope, which names the hover group the Box joins.
  33. BoxProps type The props of Box: the layout, position, margin, padding and border props of Ink's Box a tree may set, and the two of hover.
  34. BuiltinToolCallInput type One variant per built-in tool; with none in the table (a plugin author's project with no tools entry laid), one loose variant over every name.
  35. BuiltinToolCallInputFallback type The built-in branch's answer when no built-in tool is declared: every name, its args unconstrained.
  36. BuiltinToolInputs interface The arguments of each built-in tool by name, for declaration merging; empty until a declaration file adds entries, then e.tool === "Bash" narrows e to Bash's arguments.
  37. BuiltinToolName type The names of the built-in tools.
  38. BuiltinToolResults interface The structured result of each built-in tool by name, for declaration merging; empty until a declaration file adds entries, then after e.tool === "Bash" the result of next(e) is Bash's record.
  39. ButtonProps type The props of Button, every surface's pressable: an address, a label or children, the closure a press runs, and the styles a hover overrides.
  40. CatchHandler type The handler on(...).catch(handler) takes for a hook of type F: the hook's ($, e, next), run afresh when it throws, misreturns or overruns.
  41. Caught type What next carries into a .catch handler and nowhere else: why the hook failed, and whether it had called next before it did.
  42. Chunk type What a hook on streaming event N yields, and what its next(e) yields to it (ChunkOf by name).
  43. ChunkOf type The chunk type of each streaming event, by name: what its stream yields.
  44. ChunkRef type What every turn.step chunk may carry: the engine's handle on the item of its own stream the chunk was read off, absent on a chunk a hook made.
  45. ClassicEventName type The name of a classic hook event as a function-hooks event: the settings hook's own name under classic (classic.Stop, classic.PreToolUse).
  46. ClassicEventOf type The classic (settings) hook events, one per classic event name: e is the hook's whole stdin input, base fields (transcript_path, cwd) included.
  47. ClassicHookEvent type The name of a classic hook event: PreToolUse, Stop, and the rest.
  48. ClassicHookInputs type What a classic hook receives on stdin for each event, by event name: the Agent SDK's <Event>HookInput.
  49. ClassicResult type Everything a classic hook event's answer can carry, named as the classic hook's JSON output names it; each event reads its subset (ClassicResultOf).
  50. ClassicResultFields type The event-specific fields of ClassicResult each classic event reads (its hookSpecificOutput), by event; an event absent here reads none of them.
  51. ClassicResultOf type What each classic hook event's hook returns and its next(e) resolves to: the event's own subset of ClassicResult.
  52. ClassifyOptions type Options of $.model.classify.
  53. ClientElements type The element table a surface module draws with, surface.elements: the terminal's (Elements) less Client (none nests), Raster and Image.
  54. ClientKeyEvent type One key the person pressed while a Client had the focus, as surface.onKey hands it. Escape never arrives: it returns the focus.
  55. ClientModule type The component a surface module exports (default, or its one PascalCase export): from props and surface to the tree drawn (no nested Client).
  56. ClientPointerEvent type One pointer event over a Client's region, as surface.onPointer hands it: region-relative cells, and the sub-cell position where known.
  57. ClientPointerType type What the pointer did over a Client's region: a button went down, the pointer moved, the button came up, or the pointer crossed the region's edge.
  58. ClientProps type The props of Client: which of the plugin's surface modules draws here, under what key, with what data, in how much room.
  59. ClientSurface type What a surface module's function receives as its second argument: its elements, the instance's local state, its region, input, clock and port.
  60. ClockWait type The argument of the $.clock waits (sleep, after, every): how long, in milliseconds, before the dispatch resolves.
  61. CodeProps type The props of Code, source text every surface draws with the engine's own highlighter: coloured tokens, a line gutter on request, or a unified diff.
  62. Color type What a prop that paints may hold: a theme key, which follows the person's theme, or any other string, a raw color (a name such as "red", or hex).
  63. CommandDescribeInput type The input of command.describe: how one slash command presents in the typeahead and /help, at the moment the engine lists it.
  64. CommandDescribeResult type What a command.describe hook returns: the description, hint and hidden flag the menu uses; the name, immediate and provider stay as they were.
  65. CommandInfo type One slash command as $.command.list() returns it.
  66. CommandPresentation type Where a command's answer will show: which of the terminal's two layouts the surface renders, and how wide it is when the command runs.
  67. CommandRunArgs type command.run's input as a plugin's $.command.run takes it: args may be left out (/command, bare); origin and presentation the engine sets.
  68. CommandRunInput type The input of command.run: one slash command about to run, the way the person typed it (/name args), and where the run came from.
  69. CommandRunResult type What a command.run hook returns and what next(e) and $.command.run resolve to: the command's output text and the notes it leaves the model.
  70. CommandSource type Where a slash command comes from, as $.command.list() tells them apart.
  71. CommandSpec type What $.command.register takes: the slash command this plugin serves.
  72. ConfigChangeHookInput type
  73. ConfigDescribeInput type The input of config.describe: how one /config row presents, at the moment the menu lists it (and for $.config.list).
  74. ConfigDescribeResult type What a config.describe hook returns: the label, help text and hidden flag the menu uses; the key and provider stay as they were.
  75. ConfigKind type How a /config row takes its value: boolean toggles, choice picks one of its options, text takes a string, number a number.
  76. ConfigOrigin type Where a config.set came from, in prompt.submit's words: the person in the /config menu (composer), the bridge, or a plugin, named.
  77. ConfigRow type One /config row as $.config.list() returns it: what the menu would draw now, after every config.describe hook, a hidden row left out.
  78. ConfigSetArgs type config.set's input as a plugin's $.config.set(args) takes it: the row's key and the value; the engine fills the rest.
  79. ConfigSetInput type The input of config.set: one /config row about to change, from the menu or a plugin's $.config.set, with what it holds now and who owns it.
  80. ConfigSetResult type What a config.set hook returns and what next(e) resolves to: { value } once written, or { deny: reason }, the row left as it was.
  81. ConfigValue type A /config row's value as a hook and $.config see it: a toggle's boolean, a choice's or a text's string, a number, or a list of strings.
  82. ContextAgent type One custom agent whose description the Agent tool's prompt carries; built-in agents are left out.
  83. ContextBreakdownDetail type How a context breakdown is counted: full with the token-count API per category, summary from the last response's usage and local estimates.
  84. ContextCategory type One row of the breakdown, as /context lists it beside the grid (System prompt, Messages, Free space, Autocompact buffer).
  85. ContextCategoryKind type What a breakdown row is; branch on this, never on the row's name.
  86. ContextGridSquare type One square of the grid /context draws: which row it belongs to and how full it is.
  87. ContextMcpTool type One MCP tool's schema as the context carries it.
  88. ContextMemoryFile type One memory file the context carries (a CLAUDE.md, a rules file, an auto-memory entry).
  89. ContextSkill type One skill whose listing the context carries.
  90. ContextSkills type The skills the context lists for the model: how many there are, how many fit the listing's budget, and each one's share.
  91. ContextSlashCommands type The slash commands the Skill tool's prompt lists, counted.
  92. ContextWindowSource type How the window the breakdown measures against was settled; /context prints its Auto-compact window line off this.
  93. CoreEngineInterface interface The plugin's identity (plugin) and the nouns core contributes to $ as the innermost step of the engine.create fold.
  94. CoreEventName type The name of an event the engine defines itself (a key of CoreEventOf); EventName adds the declared plugin nouns' events.
  95. CoreEventOf type The argument of each event the engine defines itself: its call sites' (EngineEventOf), the classic hooks' (ClassicEventOf), the calls on $.
  96. CwdChangedHookInput type
  97. DeclaredAttachmentInput type One prompt.attachment input of a type PromptAttachmentDetailOf names: the attachment's text, and under detail the facts it was rendered from.
  98. DeclaredEvents type The state events of each declared value in a union of [plugin, key] pairs, one variant per pair (it distributes), so a matcher narrows e.
  99. DeclaredEventsOf type e of state.get and of state.set for one declared value: its typed reference, and for a write the change, of the declared type.
  100. DeclaredPair type Every named value the enabled contracts declare, as one union of [plugin, key] pairs; never while PluginState is empty.
  101. DeclaredStateChange type What a state.set on one declared value carries beside its reference: the value being written and the one that stood there, of the declared type.
  102. Derived type A value computed from other values, as derive(sources, fn) makes it: read runs fn again only when a source's version moved.

What the file says about itself

Claude Code writes the declarations with an introduction at the top, and this is it, reproduced as it ships. Until Anthropic published their mods docs with 2.1.287, it was the only guidance that came with the surface.

EARLY ACCESS: this surface may change between releases without notice. Written by the engine each time it loads a mod from a folder the person owns, beside that mod as .claude-plugin/types/claude-code/index.d.ts; written again after an update rather than edited. The first line names the Claude Code version that wrote it. TypeScript 5.4 or newer reads it. `claude plugin validate <dir>` is the other half: it reads a plugin's manifest and its hooks module's source the way the engine will and reports what the module hooks and calls and everything the engine would refuse, before any session loads it.

What is here: the module a hooks module may import types from,

import type { Register, On, EngineInterface } from 'claude-code'

(at run time the import is empty), and the globals a hooks module has: `h` and `Fragment` (what JSX compiles against), the JSX namespace, and the environment's web APIs (URL, TextEncoder, AbortController, crypto.subtle, ...). A hooks module runs in an environment of its own: no DOM, no Node. The module, and every file it imports from the plugin, is named .ts, .tsx, .jsx, .js, .mjs, .cjs, .mts or .cts (a file named otherwise is not loaded) and is an ES module whatever its suffix: there is no `require`. A file of the plugin is imported with an `import` declaration. A module holding `import()` does not load. The elements a render hook draws with (`Box`, `Text`, `Button`, ...) are not globals: they come from the surface's table,

const { Box, Text } = $.ui.resolve(e)

Also here: 'claude-code/testing', the kit a plugin's *.test.ts and *.test.tsx files import under `claude plugin test <dir>`, which runs each in an environment like the one a plugin's hooks run in (no fs, network or process), the plugin loaded from the folder by the engine's own host: `test(name, async ($, on) => { ... })`, where `$` is the engine's own and the hooks `on` registers sit beneath every plugin; with describe, expect, tier, and `mock`, whose clock, store and env answer those nouns beneath the plugins from memory. `$.ui.mount` draws a component through the plugin on the surface the test names (terminal, desktop, vscode or mobile: never assumed) and hands back the drawing to read and act on by key: find an element, press a Button, type into an Input, drive a `Client`'s module (keys, pointer, posts, its frame clock), each act typed by that surface's element table, so one test body run over several surfaces covers the mod's hooks and description on each. It exercises the mod (its hooks, the tree they return under each surface's rules, its `Client` modules), never a surface's paint (Ink's, the desktop page's):

test('notes add up on every surface that takes input', async $ => {
  for (const surface of ['terminal', 'desktop'] as const) {
    const ui = await $.ui.mount({ plugin: 'notes', surface, ...BAND })
    await ui.input({ key: 'new', text: 'milk' })
    expect((await ui.find({ key: 'count' }))?.text).toBe('1 note')
    await ui.key({ key: 'down', in: 'list' })
    await ui.unmount()
  }
  for (const surface of ['terminal', 'desktop', 'vscode', 'mobile'] as const) {
    const ui = await $.ui.mount({ plugin: 'notes', surface, ...HINT })
    expect(await ui.find({ type: 'Text', text: /notes/ })).toBeDefined()
    await ui.press({ key: 'dismiss' })
  }
})

Typing a plugin against it:

export const register: Register = (on, options) => { ... }

or, in a .js module,

/** @type {import('claude-code').Register} */
export const register = (on, options) => { ... }

A tsconfig.json (or jsconfig.json) that fits a hooks module:

{
  "compilerOptions": {
    "target": "es2023", "lib": ["es2023"], "types": [],
    "module": "esnext", "moduleResolution": "bundler",
    "strict": true, "noUncheckedIndexedAccess": true,
    "noEmit": true, "skipLibCheck": true,
    "jsx": "react", "jsxFactory": "h", "jsxFragmentFactory": "Fragment"
  },
  "include": [".claude-plugin/types", "hooks", "types", "tests"]
}

".claude-plugin/types" is where the engine lays this file (claude-code/) and, beside it, this build's built-in tools (claude-code-tools/), the MCP tools connected when the mod last reloaded (claude-code-mcp/) and one entry per plugin the mod's plugin.json lists under "dependencies" (that plugin's own contract): what it adds to `$` in engine.create, so a plugin you depend on is typed with nothing copied (the include above takes the whole folder). "hooks" is the plugin's hooks/ folder, "types" its own contract and "tests" its test files. `lib` names no DOM: the environment has none, and its `Text` would shadow the element. A mod with no tsconfig of its own has these options without writing them: the engine gives it a tsconfig.json that extends .claude-plugin/types/tsconfig.json, which carries them with that folder as the one type root.

A plugin that adds a noun to `$` ships its own contract: a .d.ts its plugin.json names as "types", exporting the noun's types at its top level and declaring the noun on the engine's interface,

export type Topo = { ... }
declare module 'claude-code' {
  interface EngineInterface { topo: Topo }
}

with no import or reference, its exported names led by the noun's PascalCase name; the plugin's own hooks module imports them from it.

Where this comes from

Claude Code carries its own type declarations for the hooks runtime. From 2.1.287 it writes them into .claude-plugin/types/ each time it loads a mod from --plugin-dir, and before that /plugin-types wrote them on request. They are not in the npm package as a file and not in the JavaScript bundle either: Claude Code decompresses an asset embedded in the binary. So documenting the surface used to mean installing a build and running it by hand, which is why nobody did it twice.

The release pipeline reads that asset straight out of the binary it already downloads, parses it, and writes a JSON document beside the rest of the release data. This section renders that document. Which means it is never a release behind, and nobody has to remember anything.

The prose about how to use any of this, what the calls cost, and which ones do not behave the way their shape suggests is the Mods Guide. This section is the inventory.

Mined from build 2.1.319 on 6 Nov 2026 . The declarations are Claude Code's own writing about itself, reproduced here; everything around them is this site's.

Feedback