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. DeriveFunction type derive(sources, fn): a value computed from atoms and references, cached by their versions: read runs fn again only when one moved.
  3. DirectoryAddedHookInput type
  4. ElementChildren type The children field every element constructor's props carry, appended beside its own props type: one child, or a list that may nest.
  5. ElementConstructor type An element as $.ui.resolve(e) hands it out: a constructor from props to the frozen plain-data element, children among the props as JSX passes.
  6. ElementName type Every element name of every surface: what a table handed out is completed to (an omitted one draws a fragment; see ui.resolve).
  7. Elements interface Each surface's primitive tags and their prop types, by e.surface, for the surfaces the plugin was compiled against.
  8. ElementTable type The table ui.resolve answers for an argument of surface P.
  9. ElicitationHookInput type Hook input for the Elicitation event. Fired when an MCP server requests user input. Hooks can auto-respond (accept/decline) instead of showing the dialog.
  10. ElicitationResultHookInput type Hook input for the ElicitationResult event. Fired after the user responds to an MCP elicitation. Hooks can observe or override the response before it is sent to the server.
  11. EngineCreateInput type The input of engine.create: the fold that builds $, once per load, core innermost.
  12. EngineCreateResult type What an engine.create hook returns: $ as built so far with this plugin's nouns added, less any it withheld.
  13. EngineEventOf type The events the engine raises at its call sites, and engine.create; the classic settings hooks' events are ClassicEventOf.
  14. EngineInterface interface $, the first parameter of every hook. Frozen; core's interface plus every noun the plugins' engine.create steps added.
  15. EngineInterfaceBuilt type What next(e) resolves to at engine.create: $ as the steps beneath built it, typed as $ is, open to nouns no declaration names yet.
  16. EngineResultOf type The engine's events' results.
  17. EnvSetResult type What $.env.set resolves to and what an env.set hook's { value } holds: {} once the variable is set or unset, or why it was not.
  18. EventCalls type The engine's own events as calls on $, one signature each: $.<noun>.<event>(input) resolves to its result, or to its stream.
  19. EventName type The name of an event: a key of EventOf, the engine's own (CoreEventName) and the declared plugin nouns' (NounEventName).
  20. EventOf type The argument of each event, by event name: what a hook receives as e and what the call on $ takes. Plain data, frozen to every depth.
  21. EventResult type The result of event N: what its hooks return and what their next(e) resolves to.
  22. Events type The hook signature of each event, ($, e, next), as one mapped type over EventOf; a streaming event's is the generator form (StreamHook).
  23. ExitReason type
  24. FileChangedHookInput type
  25. Frozen type T with every property read-only to every depth, arrays and tuples kept as declared: how a hook's e is typed.
  26. FsAncestor type One file $.fs.ancestors found: the directory it stands in, the name it was asked for by, and its text as the engine's memory loader reads it.
  27. FsAncestorPart type One file of an ancestor entry: the file itself or one it imported.
  28. FsAncestorsRequest type The argument of $.fs.ancestors: the file names to look for in each directory, the file to walk down to, and the directory to walk beneath.
  29. FsBytes type What $.fs.read(path, { as: "bytes" }) resolves with: the file's bytes, base64, since only plain data crosses into a plugin's environment.
  30. FsEntry type One entry of $.fs.list: the entry itself, a link not followed.
  31. FsReadAs type How $.fs.read answers: text (UTF-8, the default) or bytes (base64).
  32. FsReadBytesOptions type The options of $.fs.read that ask for the bytes: the call answers { base64 }.
  33. FsReadCall type $.fs.read: the file's text, or with { as: "bytes" } its bytes as { base64 }.
  34. FsReadOptions type The options of $.fs.read.
  35. FsStat type What $.fs.stat resolves with: what the path leads to, whether the path itself is a symbolic link, and where it lands when asked.
  36. FsStatOptions type The options of $.fs.stat.
  37. Glob type Every event (*), or every event under a namespace (classic.*: each one whose name starts with classic.).
  38. GlobHook type The hook on(pattern, hook) takes for a glob or a negation: one function placed on every selected event, e and the result typed as their union.
  39. GlobNext type next in a hook on a glob or a negation: an overload per selected event, then one over their union for an e not yet narrowed.
  40. GlobNextResult type What next(e) resolves to in a glob hook before e is narrowed: the NextResult of each selected event, as a union.
  41. Hook type One hook, ($, e, next), on event E.
  42. HookBudget type The time bounds every hook runs under, in milliseconds: the engine's own constants are typed by these members, and next.budget reads the live one.
  43. HookFailure type Why a hook failed, as its .catch handler reads it on next.error: plain frozen data.
  44. HookFor type The hook type per pattern: an event's own (Events), *'s (AnyEventHook), or a glob's over the events it selects (GlobHook), as one conditional type.
  45. HookInput type
  46. HookOf type The hook event E takes: an async generator over its chunks for a streaming event (StreamingEventName), ($, e, next) => result otherwise.
  47. HooksModule type What a hooks module exports: register, and nothing the loader reads besides.
  48. HookStream type What next(e) returns on a streaming event: the stream of everything beneath, chunk by chunk, whose return value is the result from beneath.
  49. HttpInit type Options of $.http.fetch.
  50. HttpResponse type What $.http.fetch resolves with.
  51. ImageBlitArgs type A $.ui.blit argument swapping one of the caller's mounted keyed Images to its next picture; every call sends it, so a stream needs no generation.
  52. ImageProps type The props of Image, the terminal surface's picture leaf: pixels over a box of cells where the terminal can (kitty and Ghostty, or iTerm2 3.5 and later for png and rgba bytes under fullscreen rendering; inside tmux too, for bytes only, with tmux's allow-passthrough and focus-events on), the alt elsewhere.
  53. ImageSource type The picture an Image shows: base64 bytes the plugin holds (at most 2 MiB decoded), or the name of a file or POSIX shared-memory object it does not.
  54. ImpossibleKeys type The keys of object pattern P that object member E cannot satisfy, D levels down; never when there is none, which is what keeps the member.
  55. IndexFree type An object with the declared keys of T and no other: its string and number index signatures are left out. What KnownKeys reads the keys of.
  56. InputProps type The props of Input, every surface's text field: an address, optional texts, and the closures a change and a submit run. A leaf.
  57. INSTRUCTION_FILE_KINDS const Every tier an instruction file can belong to, for checking a hook's answer; the kind type is derived from this list.
  58. InstructionFile type One instruction file behind the claudeMd block: where it was read, its tier, its text as loaded, and the file that @-imported it if one did.
  59. InstructionFileKind type What tier an instruction file belongs to: the organization's managed policy, the person's own, the project's checked-in or private ones, memory.
  60. InstructionsLoadedHookInput type
  61. InvalidatableEventName type What $.ui.invalidate takes: a render event, or one of the six events whose answers the engine caches for the session.
  62. IsDiscriminant type Whether tag key K selects members of I: it does when each member gives it ONE literal (component: "ToolUse" on the ToolUse variant).
  63. IsLiteralValued type Whether V is made of literals only: "a" | "b" is, string is not.
  64. IsSingleLiteral type Whether V is exactly one string, number or boolean literal.
  65. IsUnion type Whether T is a union of two or more members.
  66. JsonValue type Plain data: what JSON holds, and what crosses between a plugin's hooks module and its surface module whole (a Client's props, a post's data).
  67. KeptEvent type What next takes in a matched hook: the variants of e the matcher can match (KeptMembers), as declared, so a rewrite of a pinned field passes.
  68. KeptMembers type The members of the argument union E matcher P can match, as declared; what next takes, so a rewrite may change a field the matcher pinned.
  69. KnownKeys type The declared keys of T, the string and number index signatures left out.
  70. LateOverload type The events whose overload must come after the rest, lest it shadow them.
  71. LinkProps type The props of Link, a hyperlink every surface draws: an OSC 8 span on the terminal (else its text then the URL in dim), an anchor on desktop.
  72. Literal type What a matcher value selects by: itself, or unknown for a RegExp, which selects nothing.
  73. MarkdownLeafProps type What a Markdown carries across the boundary: its address, text, dimness and which links it answers; onLinkPress stays behind, a press instead.
  74. MarkdownProps type The props of Markdown, a block of markdown every surface draws as it draws an assistant reply's text: its own renderer, links, tables, fences.
  75. MatchedEvent type The argument a matched hook receives: e narrowed by M (Narrowed), per event the registration covers.
  76. MatchedHook type The hook on(pattern, matcher, hook) takes: ($, e, next) with e narrowed by the matcher (MatchedEvent), and a tagged result the same way.
  77. MatchedNames type The events a matched registration on P covers: the event named, or for a glob every selected event whose input has each key the matcher names.
  78. MatchedResult type What a matched hook returns: the event's result, narrowed by M where the result is a union tagged by the matcher's tag keys.
  79. MatchedStreamHook type The hook on(event, matcher, hook) takes on a streaming event: the generator form, e narrowed by the matcher, next(e) the stream beneath.
  80. MatchedStreamNarrowings type What a matched streaming hook's next.is(pattern, e) narrows e to: the streaming event's argument narrowed by the matcher.
  81. MatchedStreamNext type A matched streaming hook's next: the variants the matcher keeps, the result tagged the same way, next.is narrowing as the matcher does.
  82. Matcher type What on(event, matcher, hook) takes for an argument of type I: the shape of the e the hook wants, a partial of it at any depth.
  83. MatcherData type Any matcher at all, for a field typed unknown (a tool's input, a result's output): the kinds the engine accepts, unchecked there.
  84. MatcherFor type The matcher type per pattern: a Matcher of the e of the event named, or of each event a glob or a negation selects.
  85. MatcherKeys type The declared keys of every variant of I (index signatures aside).
  86. MatcherOne type What matches one value of type V, by the runtime's kinds: a scalar leaf takes the value or a RegExp; an object, a partial of it.
  87. MatcherValue type What a matcher gives a key whose value is V on this variant and Across over every variant: one MatcherOne, or an array of them matched as one-of.
  88. MatcherValueAcross type The type of key K across the variants of I that declare it, read variant by variant: what MatcherValueOf reads for a key as wide as symbol.
  89. MatcherValueOf type The type of key K across the variants of I that declare it: one read of their table by key (MatcherValues), for a key some variant declares.
  90. MatcherValues type The type of each declared key of I across the variants that declare it, as one table by key: made once per I, then read at a key.
  91. McpConnectRefusal type Why $.mcp.connect left a server unconnected, in one word; unlisted too where the session's host runs the plugin's servers itself.
  92. McpConnectResult type What $.mcp.connect resolves to and what an mcp.connect hook's { value } holds: the server connected, or why not.
  93. McpContentBlock type One block of an MCP result: type and the fields that kind of block carries.
  94. McpServerProvenance type The MCP server serving this tool, for mcp__* tools: name is the server's config key (for source: "sdk", exactly the name the SDK host registered in sdkMcpServers / mcp_set_servers; for any other source, the key as authored in that configuration - untrusted text, the same value mcp_status and system/init report, to be escaped before display), source is where its definition came from - sdk (an in-process server the SDK host runs; only the host can register one, so a configured server of the same name never reads sdk), plugin (a server a plugin ships or registers at runtime), or a config scope (user, project, local, dynamic for --mcp-config / mcp_set_servers process servers, managed, enterprise, claudeai, agent). Key trust on source, not on the name or the tool-name prefix. Absent for non-MCP tools.
  95. McpToolCallInput type The MCP branch of a tool.call hook's e (and of $.tool.call's input): one variant per declared tool, else the loose McpToolCallInputFallback.
  96. McpToolCallInputFallback type The e a tool.call (or classic.PreToolUse) hook receives for an MCP tool while no MCP tool is declared: every mcp__* name, loose arguments.
  97. McpToolInputs interface The inputs of the MCP tools this project knows, keyed by full tool name, for declaration merging; empty by default, then every MCP tool is loose.
  98. McpToolName type The name of an MCP tool as the engine spells it: mcp__<server>__<tool>.
  99. McpToolResult type An MCP tools/call result as the SDK returns it, plain data.
  100. MemberOfFunction type memberOf(family, e): the member of a family for the instance being drawn, keyed by e.requestId; of an atom over a family, that member's.
  101. MessageDisplayHookInput type Hook input for the MessageDisplay event. Fired with each batch of newly completed lines while an assistant message streams. Display-only: the stored message and what the model sees are untouched.

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