plugin-authoring

You are about to write, extend or debug a plugin made of function hooks. This note is orientation: what such a plugin is, where its exact contract is written down for the build you are running in, and where to look when something does not take. The API is early access and moves between releases, so treat the generated declarations as the authority and this note as the map to them.

What a plugin of function hooks is

A plugin is a folder with a .claude-plugin/plugin.json manifest. Its function hooks live in one hooks module: a TypeScript or JavaScript file that hooks/hooks.json names under modules (one path, relative to that file), exporting register(on, options). on(event, matcher?, hook) adds a hook; options holds the values of the fields the manifest's userConfig declares. Every hook has the shape ($, e, next): $ is the engine interface (display, model, session, prompt, tools, filesystem, store, clock, network, host commands, settings, environment, the config menu's rows and the rest), e is the event's input as a plain value, and next(e) continues to the other plugins and then the engine's own behaviour, resolving to the event's result. A hook that returns without calling next answers for itself; one that calls next({ ...e, ... }) rewrites what the rest of the chain sees, within what that event allows. The module runs in an environment of its own, with no DOM and no Node: everything outside it is reached through $. JSX is available with h as the factory.

The events cover tool calls and their descriptions, the prompt as submitted, the system prompt's sections and the first message's context blocks, what the interface draws, the turn's start, steps and completion, the session's start and deliveries, each hooks module's admission, skills, subagents and attribution text. Which of them a feature is, and what it needs from $, are the two questions worth settling before writing. One event streams: turn.step, a model request of the turn, whose hook is an async generator (async function* ($, e, next) {}, the one form that loads there); next(e) is the stream beneath, yield* next(e) forwards it and evaluates to the step's result, for await over it rewrites the chunks (TurnStepChunk) one at a time, yielding without next answers alone, and a chunk once yielded stays, so a hook that fails mid-stream is left where it stood and the rest of the response comes from beneath it.

The types are the reference

Do not guess at an event's input, a method on $, or an element's props. Run /plugin-types in the session (it takes an optional directory and defaults to .claude/types). It writes three files from the running build: claude-code.d.ts, which declares the module claude-code (import types from it; at run time the import is empty), the globals a hooks module has, and the inputs of this build's built-in tools; claude-code-plugins.d.ts and its folder, what the enabled plugins add to $ (below); and claude-code-mcp.d.ts, the inputs of the MCP tools connected right now, so e narrows per tool. The header of claude-code.d.ts carries a tsconfig.json that fits a hooks module and shows how to type register against Register.

Read that file for every event's input and result, every noun and method on $ with its doc comment and example, every element each surface draws and the props each element accepts, and the limits it states. Shapes there are the engine's own, not the Messages API's: $.session.messages(), for one, answers SessionMessage rows of { role, text, toolUses }, not content blocks. When the build updates, regenerate rather than edit. claude plugin validate <path> reads a plugin's manifest and its hooks module's source and reports what the module hooks and calls, which is the quickest check that the engine sees what you meant. A plugin that adds a noun to $ in engine.create ships that noun's types as a contract: one self-contained .d.ts (say types/index.d.ts) that exports the noun's types at its top level and declares the noun on the engine's interface, export type Topo = { ... } then declare module 'claude-code' { interface EngineInterface { topo: Topo } }, with no import or reference, its exported names led by the noun's PascalCase name (Topo, TopoRun), named in plugin.json as "types": "./types/index.d.ts". The plugin's own hooks module imports those types from that file, so the contract is the one place they are written. A plugin that depends on it never copies the file: /plugin-types copies every enabled plugin's contract to claude-code-plugins/<plugin>.d.ts beside an index, claude-code-plugins.d.ts, that references each, so the noun is typed on the dependent's $ from the session it develops in (the tsconfig's include of .claude/types takes the folder), and claude plugin validate checks a contract exactly as that roll-up reads it.

Developing one

claude --plugin-dir <folder> loads the plugin from disk for that session only (repeat the flag for several). In an interactive session the folder is watched: saving a file reloads the hooks module, so register runs again in a fresh environment and the previous environment's timers are dropped. Options for a plugin loaded this way are read from settings under pluginConfigs, keyed by the plugin's <name> (or <name>@inline); each non-secret userConfig field is a row in the config menu too, and a change there reloads the module with the new options. A string field that lists options ("options": ["gist", "turbo"], its default among them) is a picker over exactly those values there, and a stored value outside them counts as unset.

Run with claude --debug while developing. A hook that fails is skipped and the chain continues without it, unless its registration's .catch handler answers in its place; the transcript says so once, in a dim line naming the plugin, the event and the reason, as it names a module that did not load. The debug log has every occurrence and each result the engine refused, so a plugin that seems to do nothing has usually been told why.

Drawing: ui.render

A ui.render hook receives one component instance. e.component says which component, e.surface where it is drawn (terminal, desktop, mobile or vscode), e.requestId which instance (the tool_use_id for a tool row or dialog, the message id for a message or a command's output row, the agent id for a spinner), e.props the component's plain-data props, and e.viewport, when the surface has measured, the size it draws into in character cells: columns and rows. A change of width re-runs every hooked site once the resize settles, so a tree sized to columns stays right; a change of height alone re-draws nothing. A Pane or AbovePrompt hook sizes its tree to e.props.bodyColumns instead: the box it draws into, which is narrower than the viewport while a pane is docked beside the transcript. $.ui.invalidate asks for a redraw when the hook's own state changed.

Build trees from the table $.ui.resolve(e) returns: the surface's element constructors, destructured into the hook's JSX tags (a module has no element globals). Tables differ per surface, see Elements (mobile has no Input, Select or Client, vscode no Client, terminal no Svg but alone Raster); narrowing e.surface narrows the table. A grid of colored cells (sparkline, heat map, rendered frame) is one Raster, its cells packed per RasterProps, never a Box per cell; $.ui.blit repaints a mounted one without a render pass. Model-style text (headings, lists, tables, code fences, links; one outside https:/http:/file: draws as text) is one Markdown, drawn as an assistant reply is; given key and onLinkPress, a plain single click on a link it drew (any, or one pressableLinks names) raises ui.press carrying the link's href instead of the surface opening it, where the surface reports clicks (the fullscreen terminal; a ctrl- or alt-click still opens it). Return a tree, or next({ ...e, props }) to change what the engine draws, or next(e) to leave it. A tree that does not validate (an element the surface lacks, a prop it does not take, a child where none goes) is not drawn: the engine draws its own instead and writes to the debug log a line beginning ui.render (<Component>): a hook returned a tree that does not validate, followed by the reason. When a drawing silently falls back, that line and the element's props type are the two things to read. A Button is [ label ] on the terminal, or with plain no brackets: 1: label beside its hotkey and the label alone without one, so a one-glyph label is a one-glyph control the focus still inverts. Buttons, text fields and selects keep their handlers in the plugin and raise ui.press, ui.input and ui.select; keys reach one only while it has focus, Esc returns to the prompt, except that a Button naming one of the engine's keybinding actions (action: "app:cycleDiffBase") is also pressed by the person's chord for it from the prompt while it is mounted: chords, or a modified key Global or an active context binds, and not while an engine handler of that action is mounted. A pane opened with focus, closeOnEscape and holdToasts behaves as a dialog: it takes the keys, Tab and the arrows walk its buttons, Esc closes it, and toasts wait behind it; an element drawn holds the ring from the start, every move of the ring is the event first (its the key now holding it, absent on the engine's close mark; keeps it) and moves it while the site holds the keys; opens it inline as tall as its content needs (up to what the layout spares, and the person's own size wins), so a short dialog shows whole and its arrows walk rather than scroll; the input's says whether the answer shows fullscreen and how wide the terminal is. A keyed scopes styles, a hover groups elements across sites, and a drawn with cell offsets () paints over its surroundings without moving them, so with on it is a card that appears over the rows above a hovered glyph. Every user-role transcript row is the site: the person's prompt, a background task's notification (: its , , ) and a message another agent, teammate, session or channel sent (), told apart by , which a matcher narrows on (); a hook that draws a compact row of its own returns while (ctrl+o), so the full row still shows there, and a rewritten changes the row alone, never what the model read. A slash command's output row is the site: a plugin whose command answers with ( the row the model also reads, notes only the model reads, recorded after it) hooks it with and draws that text as a tree inline in the transcript, where a built-in command's lines would sit.

Work that outlives a dispatch

A hook runs inside one dispatch with a budget, and next.signal aborts when that dispatch is abandoned (the user interrupted, another hook settled first, the budget ran out); anything started for the dispatch should stop on it. Work meant to outlive a dispatch belongs elsewhere: start it from a session.start hook, which fires once when the session is ready and is awaited before the first prompt (so a $.tool.register awaited there is listed by turn one), and keep it going with $.clock.every and $.clock.after, whose timers run until cancelled or until the module reloads. $.prompt.submit hands the session a prompt once it is idle, so background work can wake a quiet session. $.ui.status, $.ui.toast and $.ui.log show state without starting a turn, $.store keeps values across sessions, and $.process.run runs a host command by argv.

Tools and agent types the model can call

$.tool.register declares a tool: its name, the description the model reads and its input schema; the tool is listed as mcp__<plugin>__<name>. The plugin serves it by hooking tool.call with the matcher { tool: 'mcp__<plugin>__<name>' } and returning the result, and a call no hook answers fails saying so. Registering the same name again replaces the tool, and a plugin may register several, each listed as it lands. $.agent.register declares an agent type the same way, <plugin>:<name>, from an agent definition as settings JSON spells one (prompt, tools, model, and the rest, all in force); a plugin folder's agents/*.md files declare them too. $.agent.spawn({ subagentType }) runs one and its answer is its turn.complete; an agent.offer hook returning { isOffered: false } keeps it from the model while the plugin's own spawn still runs it.