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. TypesEvery declaration in the file, verbatim, with the doc comment above it.
  2. SessionMessagesResult type What $.session.messages({ agentId }) resolves to: the messages (SessionMessage), or { deny } (SessionMessagesDeny).
  3. SessionMessagesValue type What a session.messages hook's { value } holds, for any call: the rows (SessionMessage), the Messages API form (ApiMessage), or { deny }.
  4. SessionRateLimit type One rate-limit window as the rate-limit notices read it.
  5. SessionReceiveEvent type An external-event wake the delivery's text parsed as (a GitHub relay event, a signal's notice): the envelope's attributes and its JSON body.
  6. SessionReceiveInput type The input of session.receive: one inbound delivery, sanitized, before it is queued (a relay's event, a peer's message, a message for an agent).
  7. SessionReceiveOrigin type Where an inbound delivery came from, as the bridge classified it from the server's stamps: prompt.submit's e.origin, less what never arrives.
  8. SessionReceiveResult type What a session.receive hook returns and what next(e) resolves to: the delivery that was queued, { text }, or { consumed: reason }.
  9. SessionRepo type What $.session.repo() answers: the repository's root and its origin remote, when the session is in one.
  10. SessionResume type How to come back to the session that ended: what claude --resume takes.
  11. SessionSendAddress type Whom $.session.send addresses: a recipient as the SendMessage tool names one (a string), or a session or an agent of this session by id.
  12. SessionSendArgs type session.send's input as a plugin's $.session.send(args) takes it: origin (the calling plugin) and agentId are the engine's to set.
  13. SessionSendInput type The input of session.send: one plain-text message about to leave this conversation for another agent or session; the dual of session.receive.
  14. SessionSendOrigin type Who is sending at session.send: the model through its SendMessage tool, or a plugin through $.session.send; stamped by the engine, pinned.
  15. SessionSendResult type What a session.send hook returns and next(e) and $.session.send resolve to: whether the message was delivered, and why not when not.
  16. SessionStartHookInput type
  17. SessionStartInput type The input of session.start: the session the process starts with, read the way $.session reads it at that moment.
  18. SessionStartResult type What a session.start hook returns and what next(e) resolves to: { cwd }, echoed by core; a hook's own value does not change the session.
  19. SessionUsage type What $.session.usage() answers: when the session began, the context window's fill, the account's rate-limit windows and the session's cost.
  20. SessionUsageArgs type What $.session.usage(args) takes: nothing for the status line's figures alone; breakdown to have the window broken down as /context breaks it.
  21. SessionVersion type What $.session.version() answers: the version of the engine the session runs on, the release that version is built from, and when it was built.
  22. Settings type What $.settings.read answers: an object keyed as a settings.json is (permissions, env, hooks, model, enabledPlugins, ...).
  23. SettingsKeyRead type A read of one key: the key, and optionally the one source asked. It is the read of the object, projected: no event of its own.
  24. SettingsLayer type One layer a settings read is made of: what one source holds, as that source loads. The engine's merge is a fold over the layers.
  25. SettingsLayerSource type Whose settings one layer of a read holds: a settings source, or plugin, the base the enabled plugins' own settings make, beneath user.
  26. SettingsObjectRead type A read of a settings object: the settings merged over every source, or the one source asked. It names no key.
  27. SettingsReadArgs type What a settings.read call carries to the host: the one source asked, or none for the settings merged over every source.
  28. SettingsReadInput type The event settings.read as a hook receives it: what was asked, and the layers the answer is made of. One event, one granularity: the whole read.
  29. SettingsReadOverloads type $.settings.read by what it is asked: a key resolves to that key's value, anything else to a settings object.
  30. SettingsSource type One source of settings by the name a plugin gives it, lowest precedence first; the engine's own name is the same word with Settings appended.
  31. SetupHookInput type
  32. Shaped type A value kept with a shape tag, as an atom given { shape } keeps it: a reload whose code names another tag reads the value as absent.
  33. ShapedValue type What an atom given a shape reads and takes for a key declared Shaped<T>: T; never for a key declared otherwise, so that atom does not compile.
  34. SiteScroll type Where a site's window sits over the tree a hook drew in it (a pane's body, the band): the engine's to move (the person scrolls), the plugin's to read.
  35. SiteView type Which transcript the person has on screen where a site draws: the main conversation's, or one agent's, opened from the tasks list.
  36. SkillFrontmatter interface What a skill's file declares above its text, parsed and JSON-safe: each key as YAML reads it, none respelled, each value whatever JSON holds.
  37. SkillFrontmatterList interface A YAML sequence in a skill's frontmatter, as JSON holds it.
  38. SkillFrontmatterValue type One value in a skill's frontmatter: what JSON holds, and assignable to and from JsonValue.
  39. SkillPromptArgs type skill.prompt's input as a call takes it: frontmatter and source may be left out, as a caller written before the event carried them does.
  40. SkillPromptInput type The input of skill.prompt: one skill's prompt, at the moment the engine expanded it for the model.
  41. SkillPromptResult type What a skill.prompt hook returns: the text the model reads for that skill.
  42. SkillSource type Whose words a skill is, in the engine's own words: the settings tier whose skills folder holds it, or what else provides it.
  43. SleepOptions type Options of $.clock.sleep.
  44. SourceValues type The values derive's function receives for its sources, in their order: an atom's or a derived value's own, a plain reference's or undefined.
  45. Space type A Box's spacing: a number of character cells, the same on every surface, or a step name that each surface sizes its own way. The terminal and VS Code draw a step as cells: across, xs and sm 1, md 2, lg 3, xl 4; down, xs and sm 0, md and lg 1, xl 2. Desktop and the phones each use their own spacing scale, so there a step can be larger or smaller than those cells.
  46. SpeakOptions type Options of $.audio.speak.
  47. SpeakRequest type The argument of $.audio.speak(text, options) as the event carries it.
  48. SpeakResult type What $.audio.speak resolves with once the utterance has ended.
  49. StarNext type next in a * hook: the set of events is open at runtime, so e is unknown until next.is(pattern, e) narrows it to events it knows.
  50. StateAddress type Which named value a $.state call is about, as it crosses to the host: the owning plugin, the key, and a family member's id.
  51. StateDollar type What the state library's read and update take of $: its state noun, on which they make the calls a hook would make itself.
  52. StateFamily type A key of PluginState that holds one value of type T per id (one per drawn row, per worker): its reference must carry id: string.
  53. StateGetEvent type e of state.get: one variant per value a contract declares, so a matcher on plugin and key narrows it; the untyped address while none does.
  54. StateName type Which named value: the plugin that owns it and its key there, both literals where a contract declares the value.
  55. StateRead type What $.state.get answers: the value and the version it stands at; a value never written is undefined at version 0.
  56. StateRef type A typed reference to one named value: the owning plugin and the key, both literals, and for a StateFamily key the member's id.
  57. StateSetEvent type e of state.set: one variant per value a contract declares, so a matcher on plugin and key narrows e.value; the untyped write while none does.
  58. StateSetOptions type The options of $.state.set: ifVersion makes the write conditional on the value still standing at that version (compare-and-set).
  59. StateSetResult type What $.state.set answers: whether the write landed, and the version the value stands at now (a landed write's own, a missed one's the current).
  60. StateValue type The type of the value under key K of plugin P, as its contract declares it in PluginState; a StateFamily's member type for a family key.
  61. StateWrite type A $.state.set as it crosses to the host and as its hooks see it when no contract declares the value: the address, the value, and the condition.
  62. StopFailureHookInput type
  63. StopHookInput type
  64. StreamHook type The hook a streaming event takes: async function* ($, e, next) {}, yielding the event's chunks and returning its result.
  65. StreamHookBody type What a hook on a streaming event evaluates to: the async generator an async function* makes, yielding C and returning R or nothing.
  66. StreamingEventName type The events that stream: their hooks are async generators, next(e) is the stream of everything beneath, and the result is what it returns.
  67. StreamNext type The rest of the chain as a hook on a streaming event receives it: Next, except that next(e) is the stream beneath (HookStream), not a promise.
  68. StyledElement type The shape a Box and a Text share in a render tree: allowlisted props, an optional hover, the group stamp a hover.scope earns, the mark of the plugin whose drawing starts there, and children.
  69. SubagentStartHookInput type
  70. SubagentStopHookInput type
  71. SvgProps type The props of Svg, the remote surfaces' vector leaf: the markup is the element's data, as a string is a Text's, drawn isolated.
  72. TagKeys type The keys among Among a matcher may select variants of I by: valued by literals in every variant, one literal per variant (IsDiscriminant).
  73. TargetTier type A tier next.to(e, tier) may name: one a floor can reach past links of less authority to, so never prepend, which nothing skips to; user is for a prepend hook alone, and skips the peers below it.
  74. TaskCompletedHookInput type
  75. TaskCreatedHookInput type
  76. TeammateIdleHookInput type
  77. TelemetryAttribute type One attribute of a collector record, as the collector receives it.
  78. TelemetryChoice type A string property of a first-party row: the value and the list it is chosen from, so no free text reaches a row.
  79. TelemetryDestination type Where a telemetry record goes: anthropic, Anthropic's first-party analytics, or collector, the one the session's operator configured.
  80. TelemetryLogArgs type What a call of $.telemetry.log passes: a first-party row, to optional, or a collector record.
  81. TelemetryLogInput type The input of telemetry.log: one record about to be logged to the destination to names, which is always present and pinned.
  82. TelemetryLogResult type What a telemetry.log hook returns and next(e) resolves to: { value: undefined }, or { deny }, which rejects the caller's promise.
  83. TelemetryMarkInput type The input of telemetry.mark: one use of a feature, as the CLI's own feature events mark one.
  84. TelemetryMarkKind type How one use of a feature went, as the CLI's own feature events count it.
  85. TelemetryMarkResult type What a telemetry.mark hook returns and next(e) resolves to: { value: undefined }, or { deny }, which rejects the caller's promise.
  86. TelemetryProp type One property of a first-party row or a mark: a number, a boolean, or a string chosen from a list (TelemetryChoice).
  87. TelemetryRecordEntry type A record for the telemetry collector the session's operator configured.
  88. TelemetryRowArgs type A first-party row as a call passes it: to left out reads as anthropic.
  89. TelemetryRowEntry type A first-party row as a hook reads it: to is always present, the engine having completed it before any hook or matcher reads e.
  90. TelemetrySpan type The span a collector record belongs to, as W3C trace context spells it: the ids in lowercase hex.
  91. TextHoverProps type The Text props a hover may override (its colors and styles, not its wrapping) and scope, the hover group it joins; a Button's label too.
  92. TextProps type The props of Text: colors, styles, and the size, weight, face and digits each surface draws its own way. Colors are a theme key or a raw color.
  93. ThemeBackdrop type The backdrop attribute of $.theme.set: what is drawn behind the conversation, and how the surface frosts its panels over it.
  94. ThemeBackdropGlass type How a surface keeps its text readable over a backdrop: the desktop app frosts its own panels, and the mobile app lays one veil over the backdrop. Each key absent takes the surface's default, so {} is the default glass.
  95. ThemeKey type The theme keys named for what a color means: text, status, the prompt box and its modes, and diffs, as the custom theme reference lists them.
  96. ThemeResult type What $.theme.set and $.theme.clear resolve to, and what a theme.set or theme.clear hook's { value } holds.
  97. ThemeSetArgs type The argument of $.theme.set: one object of named attributes, so a later attribute is an addition and never a change of the call.
  98. Tier type One of the chain's five tiers (TIERS), outermost first; on every next.trace entry, and what next.to(e, tier) names.
  99. TIERS const The chain's five tiers, outermost first: earlier is outer is more authority, and same-event hooks nest in this order and no other way.
  100. Timer type A pending timer from $.clock.after / $.clock.every.
  101. TimerCall type A timer on $.clock (after, every): fn runs after ms milliseconds, once or until cancel().

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