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. read const Reads an atom, a derived value or a reference through $.state.get; while a ui.render hook draws, that subscribes the drawing.
  3. update const Reads, applies fn in the plugin's environment, writes with ifVersion, and tries again on a miss: what a handler closure calls.
  4. h const The JSX factory (classic runtime, @jsx h; the engine prepends the pragma): a plain-data element from a string tag or a component.
  5. Fragment const <>...</>: a column Box around the children.
  6. JSX namespace JSX over the element table: every tag is a constructor from $.ui.resolve(e) (const { Box, Text } = $.ui.resolve(e)), typed by its props; there are no intrinsic (string) tags.
  7. AbortSignal interface
  8. AbortController interface
  9. TextEncoder interface
  10. TextDecoder interface
  11. URLSearchParams interface
  12. URL interface
  13. atob function
  14. structuredClone function
  15. AsymmetricMatcher type A value that matches by a rule inside toEqual and its kin (expect.any, expect.objectContaining), known by its text in a failure.
  16. AsyncMatchers type The same checks on what a promise received settles with, each resolving once the promise has settled and the check passed.
  17. ClassicEvent type A classic hook event the engine raises on its own, by its own name (SessionStart, Stop): all but PreToolUse, which rides tool.call.
  18. ClassicFields type What $.classic.<Event> takes: the event's own fields as its hook sees them on e, less what the engine stamps at every call site.
  19. ClientScope type Which Client of a mounted drawing an act or a read means, by the key its element carries; optional while the drawing holds exactly one.
  20. Constructor type A class, as toThrow, toBeInstanceOf and expect.any take it.
  21. describe const A group of tests: its name leads the title of each test declared inside, and its body runs at once, while the file loads.
  22. ElementOfAct type The element each surface-dependent act of a mounted drawing reaches: a handle carries the act only where the surface's table has the element.
  23. ElementQuery type What a mounted drawing's find and findAll match an element on, every field given at once: its tag, its key, and the text it shows.
  24. Engine type What a test holds as $, the engine's own: every call on it is made as the REPL, the query loop and the render sites make theirs, over every plugin.
  25. EngineCall type One call on the engine's $: the event's input whole, as an engine call site passes it, to its result, or for a streaming event to its stream.
  26. EngineClassic type The classic (settings) hook events as the engine raises them: each a call running the classic.<Event> chain over every plugin hooked on it.
  27. EngineInput type A surface typing into an Input a test rendered: the ui.input chain over every plugin hooked on it, the Input's own handler last.
  28. EngineMount type A surface drawing a component instance through the plugins, then driven by key through a handle typed by that surface (Mounted).
  29. EngineNoun type One noun of the engine's $: each of its events as the engine calls it, tool.call typed per tool and ui.render per component, ui.resolve out.
  30. EngineNounEvent type The events of one noun a test's $ carries: every one but ui.resolve, which a render hook calls on its own $ and the engine never raises.
  31. EnginePress type A surface pressing a Button a test rendered, or a Markdown's link: the ui.press chain over every plugin hooked on it, its own closure last.
  32. EngineSelect type A surface picking an option of a Select a test rendered: the ui.select chain over every plugin hooked on it, the Select's own onSelect last.
  33. EngineToolCall type $.tool.call on a test's $: a call as the engine raises one, agentId the loop it runs in (a subagent's, a teammate's); left out, the main loop.
  34. Expect type The checks on a value (expect(received)), and with them the matchers that stand inside an expected value (expect.any(Number)).
  35. expect const Checks a value: expect(received).toEqual(expected) throws an AssertionError naming both sides when it fails, a message given leading.
  36. Expectation type What expect(received) answers: the checks, their negation, and the checks on what a promise received resolves or rejects with.
  37. Expecting type expect(received, message?): the checks on a value, a message of the test's own leading a failure's.
  38. FoundElement type One element of a mounted drawing as find returns it: the description the plugin's hook (or a Client's module) built, read as plain data.
  39. InputTarget type What $.ui.input takes: the plugin whose hook drew the Input, its key, the field's text, which input it is, instance and surface when several.
  40. Matchers type The checks expect(received) offers; each throws an AssertionError when it fails, naming what was expected and what was received.
  41. Matching type The matchers that stand inside an expected value, each matching received there by a rule instead of by equality.
  42. Mock type The world beneath the plugins, mocked noun by noun: each member registers hooks of the test's on on, visible where the test calls it.
  43. mock const The world beneath the plugins, mocked noun by noun: mock.clock, mock.store, mock.env and mock.session.
  44. MockClock type The clock mock.clock hands back: the time its hooks answer, and the only ways it moves.
  45. MockClockOptions type Where a mocked clock starts: now, in milliseconds (0 when not given).
  46. MockSession type The session mock.session hands back: what was appended to its conversations while the test ran.
  47. Mounted type A drawing of component C the test mounted on surface P: reads over its description, acts on its elements by key, Client acts where P has one.
  48. MountedMembers type Every member a mounted drawing of component C can have; Mounted<P, C> keeps the ones surface P has the element for (ElementOfAct).
  49. MountInputTarget type What a mounted drawing's input takes: the Input's key, the text, which of the two inputs it is (submit when unsaid), another plugin's name.
  50. MountKeyEvent type What a mounted drawing's key takes: the key as a Client's onKey listener receives it (ClientKeyEvent), and which Client when several.
  51. MountPointerEvent type What a mounted drawing's pointer takes: the event as a Client's onPointer listener receives it, in its region's cells, and which one.
  52. MountPressTarget type What a mounted drawing's press takes: the Button's key, another plugin's name when the Button is not the mounted plugin's, a link.
  53. MountResizeTarget type What a mounted drawing's resize takes: a Client region's size in cells, as the surface measuring it hands it, and which Client.
  54. MountSelectTarget type What a mounted drawing's select takes: the Select's key, the picked option's value, another plugin's name when the Select is not its own.
  55. MountTarget type What $.ui.mount takes: whose elements the test will act on, the surface that draws, and the component instance the engine asks the plugins for.
  56. Negatable type A set of checks and, under not, the same set passing where they fail.
  57. Plugin type Written inline in a test and loaded as a plugin folder is: its name, the tier it loads in (user when not given), and its hooks module's register.
  58. PluginTier type A tier a plugin loads in: every tier but the engine's own.
  59. PressTarget type What $.ui.press takes: the plugin whose ui.render hook drew the element, the key it gave it, the instance and surface when several, a link.
  60. SelectTarget type What $.ui.select takes: the plugin whose hook drew the Select, its key, the picked option's value, instance and surface when several.
  61. test const One test: it passes when its body returns or resolves, and fails when it throws, rejects or outlasts its time (5000 ms, or timeoutMs).
  62. TestBody type A test: the engine's $, and on, a plugin's registrar, whose hooks sit beneath every plugin; beneath them the bottom hook throws, naming its event.
  63. TestOptions type What test takes beside its name: the inline plugins it loads beside the one under test, and how long it may run (5000 ms when not given).
  64. TestRest type What follows a test's name: its body, or its options then its body.
  65. ThrowExpectation type What toThrow compares the thrown error with: a substring or pattern of its message, its class, a value carrying the whole message, or nothing.
  66. tier const Says which tier the plugin under test loads in, once, at the top of the file: prepend, user (when unsaid), append or builtin.
  67. WithMessage type An error-like value toThrow compares by its whole message.

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