Lookup tables for Claude Code mods - files, the on() function, every event, mods API namespaces, render sites, elements, limits, settings and commands.
This is the lookup page for mods: files, the hook function, events, API namespaces, render sites, elements, limits and settings, current as of Claude Code v2.1.290 for the CLI and Desktop app. For explanations and worked examples, follow the links to the guide pages.
Note: The authoritative reference is the TypeScript declarations Claude Code writes into your mod's .claude-plugin/types/ folder on each load (see /docs/plugins/mods/create). A copy lives at mods/types/claude-code.d.ts in the anthropics/claude-code GitHub repository, but may lag your installed version. When anything disagrees, trust your local types.
Files
File
Required
Contents
.claude-plugin/plugin.json
Yes
Standard plugin manifest. No mod-specific required fields
hooks/hooks.json
Yes
modules: an array with one path (relative to this file) to the hooks module, e.g. "modules": ["./register.js"]. May also contain settings hooks under hooks
Type declarations, e.g. types/index.d.ts, named by types in the manifest
When using $.state or adding an API namespace
Declares PluginState values and any added namespace
*.test.ts, *.test.tsx
No
Tests for claude plugin test
register receives on and options. options carries the plugin's userConfig values with defaults applied.
The on function
on(eventName, [matcher], hook) // returns a registration with .catch(handler)
The optional matcher filters on event fields; see /docs/plugins/mods/events. .catch sets an error handler for that one hook.
Hook argument
Meaning
$
The mods API. Always write calls in full, e.g. $.fs.read('notes.md')
e
Event input, deeply frozen. Pass a modified copy to next to change it
next(e)
Calls later hooks then Claude Code's behaviour; resolves to the result
next.signal
AbortSignal fired when the event is abandoned
next.origin
{ plugin, tier } of whoever fired the event. Claude Code is { plugin: 'engine', tier: 'core' }. Mod tiers: prepend, user, append, builtin
next.budget
ms (total time limit) and remainingMs
next.to(e, tier)
Skip ahead to append, builtin or core. Only for mods in prependPlugins or appendPlugins
next.error, next.called
In .catch only. next.error.kind is throw or timeout, next.error.message the text; next.called is true if the failed hook had called next
Events
Hooks on turn.step and process.spawn are async generators; all others are async functions. In the "Can return" column, next(e) means pass through, next({ ...e, x }) means pass a modified copy, and a bare object means answer without calling next.
Tools
Event
Fires
Can return
tool.call
A tool is about to run
next(e), { deny: reason }, { result }
tool.check
Claude Code decides whether a call may run, after tool.call and PreToolUse hooks. next(e) resolves to the decision so far
Once per app, render site and mod when mods load; produces the element table $.ui.resolve(e) reads
ui.press, ui.input, ui.select
A mod-drawn Button, Input or Select is used
ui.focus, ui.scroll
Focus or scroll position of a pane or the band is about to change
ui.close
A pane is about to close. e.id is the pane; e.origin.kind is plugin, person or unload
ui.message
A Client element posts data to its mod
ui.fault
A Client element failed to load, draw or run. e.phase: load, render, run; e.reason: message (v2.1.289+)
Other mods
Event
Fires
Can return
plugin.register
A hooks module is about to load. e.uses lists its events, API calls (without $., e.g. fs.read), env vars and state, as validate prints them
{ refuse: reason }
engine.create
The mods API is being built for a mod
A modified API (to add a namespace; non-user tiers can also withhold one)
Telemetry
Event
Fires
Can return
telemetry.log, telemetry.mark
A telemetry record is about to be logged, or a feature use marked
next(e), { deny: reason }
In an installed mod, telemetry hooks must use the filter { to: 'collector' }, as in on('telemetry.log', { to: 'collector' }, hook), or validate fails. The * wildcard does not match these events.
Settings hook events and API calls as events
Every settings hook event is available as classic.<Event>, for example classic.Stop or classic.PostToolUse. e is that hook's stdin JSON.
Every mods API method is also an event named <namespace>.<method>, such as fs.read, model.complete or ui.open. A hook there intercepts calls from mods running after it and can return next(e), { deny: reason } or { value }.
submit, read, fill, suggest, compose. submit({ text }) is introduced to Claude as coming from your mod; add asUser: true to send it as the user's words
$.turn
abort
$.session
messages, cwd, root, model, turns, id, repo, surfaces, usage, version, compact, send, append, authorize. usage() returns { startedAt, context, rateLimits, cost } with context holding tokens, window, percent and rateLimits a list of { kind, percentUsed, resetsAt }
$.config
list, set
$.settings
read
$.env
get, set
$.fs
read, write, list, exists, stat, ancestors. write is not atomic; use $.store for data several sessions change
$.store
get, set, delete, keys. Key-value store shared by every session on the machine
$.state
get, set, plus helpers atom, read, update, derive, memberOf imported from claude-code
$.clock
now, sleep, after, every
$.http
fetch
$.process
run, spawn
$.mcp
call, connect (connect(server) only for servers your own manifest lists)
$.audio
play, speak
$.telemetry
log, mark (only sent when Claude Code or a built-in mod calls it)
Render sites
Each site is a value of e.component in a ui.render hook. e.surface is terminal or desktop.
text, origin, isExpanded, and task or from by origin
Message id
Terminal, Desktop
AssistantMessage
The reply's text
Message id
Terminal, Desktop
ToolUse, ToolResult, ToolGroup
Tool name, input, result
Tool call id
Terminal, Desktop
CommandOutput
command, text
Message id
Terminal, Desktop
AskUserQuestion
Question and options
Tool call id
Terminal, Desktop
ToolProgress
kind
Tool call id
Terminal
Spinner
word, message, suffix, mode
Agent id
Terminal, Desktop
TurnDuration
word, durationMs
Message id
Terminal
InfoNotice
text, command
Message id
Terminal
SessionMode
modes
Single instance
Terminal, Desktop
PromptHint
isDraft, isWorking, hint
Single instance
Terminal, Desktop
e.viewport has columns, rows and isFullscreen, and is absent until the window is measured. Its rows is the whole window, not your pane.
Sizing your tree:
Width of a pane or the band: e.props.bodyColumns.
Height of a docked pane (placement: 'dock'): e.props.scroll.bodyRows.
Height of an inline pane above the prompt (placement: 'inline'): the pane grows with your tree up to bodyRows. Ask for a different limit with rows on $.ui.open.
PNG or RGBA bytes up to 2 MiB, or a file path; columns and rows up to 255; alt
Yes
Extra Button rules:
action names one of Claude Code's keybinding actions; the user's binding for it presses the button when that binding is a chord or modified key.
A digit hotkey on a button in the band also fires when the user types that digit alone into an empty prompt and pauses.
If two buttons in one drawing share a hotkey, the later one wins.
autoFocus accepts only true on any control; omit it otherwise.
Box border styles
borderStyle
Terminal draws
Top edge
'single'
Thin lines, square corners
┌──┐
'double'
Double lines
╔══╗
'round'
Thin lines, rounded corners
╭──╮
'bold'
Thick lines
┏━━┓
'singleDouble'
Thin top and bottom, double sides
╓──╖
'doubleSingle'
Double top and bottom, thin sides
╒══╕
'classic'
ASCII +, -, |
+--+
'arrow'
Arrows pointing inward
↘↓↓↙
'dashed'
Dashed lines, blank corners
╌╌
'quote'
A ▎ bar on the left only
Blank
Any other value (a common slip is 'rounded') draws no border.
Limits
Hooks exceeding a time limit are skipped; calls exceeding a size limit are rejected.
Limit
Value
A hook's own run time per event (excludes time in next and API calls other than $.clock.sleep)
10 s; 50 ms for prompt.edit
.catch handler
1 s
All session.end hooks together
The SessionEnd hook budget, 1.5 s by default, counted after settings SessionEnd hooks finish
$.process.run timeout
30 s default, 10 min max
$.model.completemaxTokens
1024 default, up to 64,000 or the model's output limit
$.fs.read, $.fs.write
4 MiB per file
Text drawn per tree
First 100,000 characters
$.store
4 MiB of JSON in total
$.session.messages()
Newest 4,096 entries
$.ui.invalidate('ui.render') redraws
10 per second; 30 in the terminal for the visible pane, expanded band and the hint line. Extra calls coalesce
$.ui.toast
Shown 4 s unless { timeoutMs } given
A pane opened without user action
Placed from 144 terminal columns, 110 once the user has opened it themselves
Command, tool, subagent type and pane names
Letters, digits, _, -; up to 64 characters
One claude plugin test test
5 s unless the test sets timeoutMs
Settings and environment variables
Name
Read from
Effect
CLAUDE_CODE_PLUGIN_DIRS
Environment, or env in ~/.claude/settings.json
Directories to load as --plugin-dir would. Absolute paths separated by : (; on Windows)
CLAUDE_CODE_PLUGIN_DIR_WATCH
Environment
1 makes long-running non-interactive sessions reload --plugin-dir mods on save
prependPlugins, appendPlugins
Managed settings (user settings only on machines with no managed settings, for users not signed in on Team or Enterprise)
Plugin ids such as acme-guard@acme-tools. Prepended mods run before every user mod, appended after, in listed order
allowManagedModsOnly
Managed, as an option on the built-in guard
Only organisation and built-in mods run their hooks. Users' settings hooks continue
allowModsToOverrideDenyRules
Managed, as an option on the built-in guard
Lets a user-installed mod approve a call a deny rule refuses
allowManagedHooksOnly
Managed
Blocks hooks and installed mods that are not the organisation's
disableAllHooks
Any settings file
In managed settings, nothing from installed plugins runs. In your own settings, organisation-managed items keep running
disableSideloadFlags
Managed
Rejects --plugin-dir and --plugin-url at startup
pluginConfigs
User or managed
userConfig values for a mod, keyed by plugin id (acme-guard@acme-tools) or name@inline for --plugin-dir mods
sec-default@builtin (shown as cc-plugin-sec-default) is the built-in guard. It loads ahead of user-installed mods on machines with managed settings or for users signed in on Team or Enterprise. If managed prependPlugins is set, the guard loads only if that list names it, at that position. Its source is in mods/sec-default in the anthropics/claude-code repository.
Commands
Command
Does
/plugin
Shows a line such as 1 mod active · edit-meter when a non-built-in mod has loaded
claude plugin validate <dir>
Reports errors, handled events and API calls. --strict treats warnings as errors; --json prints machine-readable output
claude plugin test [dir]
Runs every .test.ts/.test.tsx under the directory (default: current). Exit 1 on failure
claude --plugin-dir <dir>
Loads a plugin for one session and hot-reloads the module on save. Repeatable