Files, Nouns, and Gates

A mod has a few files, one object named $ with 20 nouns, and a short list of switches that can stop it. The tables below list them all, with the limits that apply. The one file that makes a plugin a mod is modules in hooks/hooks.json. A manifest has no mods key.

These switches stop mods: disableAllHooks, allowManagedHooksOnly, allowManagedModsOnly, --safe-mode, and --bare. A remote rollout switch also gates installed mods. Mods live in the plugin folder, plugin.json, hooks/hooks.json, and settings files.

Official pages: Mods Reference, Mods Overview, Plugins Reference, Manage Mods for Your Organization.

Example

hooks/hooks.json

{ "modules": ["./register.js"] }

.claude/settings.json

{ "disableAllHooks": false }

Files and Manifest Keys

Item	Status	What it does	How it works	Where it can be used
hooks/hooks.json key modules	Documented: An official docs page names this item.	The path of the hooks module.	One path only. The module and each file it imports end in .ts, .tsx, .jsx, .js, .mjs, .cjs, .mts, or .cts. The program says: hooks.json modules names one hooks module per plugin.	Plugin hooks/ folder.
register(on, options)	Documented: An official docs page names this item.	The export that the loader reads. The loader reads nothing else.	See Hooks.	The hooks module.
Manifest key types	Documented: An official docs page names this item.	Path to the type contract of the plugin. It starts with ./.	A self-contained .d.ts with no import, export-from, require, or reference. It declares the noun in declare module 'claude-code' { interface EngineInterface { ... } } and the PluginState values. claude plugin validate checks it.	plugin.json
Manifest key dependencies	Documented: An official docs page names this item.	Plugins that must be enabled.	A mod that lists a plugin here gets its contract at .claude-plugin/types/<plugin>/index.d.ts when the engine loads the mod from a folder the person owns.	plugin.json
Manifest key userConfig	Documented: An official docs page names this item.	Fields whose values reach register as options.	The engine fills in defaults. Values are in pluginConfigs of settings. A required field with no value fails the load. PluginOptions is a read-only record of string, number, boolean, or string list.	plugin.json
.claude-plugin/types/	Documented: An official docs page names this item.	The engine writes claude-code/index.d.ts, claude-code-tools/, claude-code-mcp/, and one folder for each dependency here.	The engine writes them again after an update. A mod that has no tsconfig gets one that extends .claude-plugin/types/tsconfig.json.	A mod loaded from a folder the person owns.
Tests *.test.ts, *.test.tsx	Documented: An official docs page names this item.	claude plugin test [dir] runs them.	See Testing.	Plugin folder.

The Dollar Object

$ is the first argument of every hook. It is frozen. It has plugin, 20 nouns, and every noun that an engine.create hook added. Write each call in full, such as $.fs.read('notes.md'). Each $ call is also an event with the same name, such as fs.read. A hook on it can pass the call on, refuse it with { deny }, or answer it with { value }. The dispatch skips the calling hook alone, so a plugin does not trap itself.

Item	Status	What it does	Members	Page
$.plugin	Documented: An official docs page names this item.	This plugin as loaded: its manifest name and its directory.	name, root	Plugin
$.ui	Documented: An official docs page names this item.	Display: a line under an open dialog, redraws, log lines, panes, scroll, focus, the clipboard.	notice, invalidate, blit, resolve, log, ask, toast, notify, status, open, close, panes, scroll, focus, copy, selection, view	UI
$.model	Documented: An official docs page names this item.	Completions through the session's own client.	complete, fork, classify	Model, Audio, and MCP
$.audio	Documented: An official docs page names this item.	Sound: clip playback and platform speech.	play, speak	Model, Audio, and MCP
$.mcp	Documented: An official docs page names this item.	The engine's MCP servers: call a tool of a connected one, or connect one the plugin lists.	call, connect	Model, Audio, and MCP
$.session	Documented: An official docs page names this item.	The running session as plain data, compacting it, and sending a message to another agent or session.	messages, cwd, root, model, turns, id, repo, surfaces, surface, usage, version, compact, send, append, identity	Session
$.turn	Documented: An official docs page names this item.	The running model turn: ending it.	abort	Turn and Prompt
$.prompt	Documented: An official docs page names this item.	Submitting a prompt as a user turn, and the prompt box: read, write, paint, or propose into.	submit, read, media, fill, paint, suggest, compose	Turn and Prompt
$.tool	Documented: An official docs page names this item.	The tools the model has in this session, and running one.	list, call, check, register	Tool, Command, and Config
$.command	Documented: An official docs page names this item.	The slash commands the person can run, and running one.	list, run, register	Tool, Command, and Config
$.config	Documented: An official docs page names this item.	Every row of the /config menu, including each enabled plugin's userConfig fields.	list, set	Tool, Command, and Config
$.telemetry	Documented: An official docs page names this item.	Analytics records and feature marks.	log, mark	Telemetry
$.agent	Documented: An official docs page names this item.	Subagents.	spawn, list, register	Agent
$.fs	Documented: An official docs page names this item.	The file system as the engine process reaches it. A relative path is under the session's working directory. Text is UTF-8.	read, write, list, exists, stat, ancestors	Files, Store, and State
$.store	Documented: An official docs page names this item.	This plugin's key-value store. It lasts across sessions and hot reloads. Values are JSON.	get, set, delete, keys	Files, Store, and State
$.state	Documented: An official docs page names this item.	Named values the host holds for the session, each with a version. They survive a hot reload.	get, set	Files, Store, and State
$.clock	Documented: An official docs page names this item.	Time and timers, each an event through the host.	now, sleep, after, every	Clock, HTTP, Process, Env, and Settings
$.http	Documented: An official docs page names this item.	The network, through the host.	fetch	Clock, HTTP, Process, Env, and Settings
$.process	Documented: An official docs page names this item.	Commands on the host, run as the user of the session. CLI only.	run, spawn	Clock, HTTP, Process, Env, and Settings
$.settings	Documented: An official docs page names this item.	What the settings files, --settings, and managed policy hold. Read only.	read	Clock, HTTP, Process, Env, and Settings
$.env	Documented: An official docs page names this item.	The environment of this process. Every Bash child, MCP server, and $.process.run command started later inherits it.	get, set	Clock, HTTP, Process, Env, and Settings

Modules

Item	Status	What it does	How it works	Where it can be used
claude-code	Documented: An official docs page names this item.	Types only. import type { Register, On, EngineInterface } from 'claude-code'. At run time the import is empty.	Exports 585 declarations. The values atom, derive, memberOf, read, and update are the state helpers. See Files, Store, and State.	Hooks modules and contracts.
claude-code/testing	Documented: An official docs page names this item.	The kit for claude plugin test: test, describe, expect, mock, tier.	See Testing.	*.test.ts and *.test.tsx
Globals h, Fragment, JSX	Documented: An official docs page names this item.	JSX compiles against them.	See Surfaces, Elements, and Render Sites.	Files with JSX.

Gates That Stop Mods

Item	Status	What it does	How it works	Where it can be used
disableAllHooks	Differs: The official docs and the program disagree. The row says how. The schema also says it stops the statusLine command. The Hooks Reference names only hooks.	No mod or hook of an installed plugin runs. Built-in mods load.	Row: Hooks, Plugins, and Skills Settings.	Settings files.
allowManagedHooksOnly	Documented: An official docs page names this item. Managed Only: Works only in managed (organization policy) settings.	Blocks hooks and mods that are not the organization's.	The program says: hooks modules are turned off here (disableAllHooks, allowManagedHooksOnly or a policy). Row: Hooks, Plugins, and Skills Settings.	Managed settings.
allowManagedModsOnly	Documented: An official docs page names this item.	Only organization mods and built-in mods run their hooks.	An option of the built-in guard sec-default.	Managed settings.
allowModsToOverrideDenyRules	Documented: An official docs page names this item.	Lets an installed mod approve a call that a deny rule refuses.	An option of the built-in guard.	Managed settings.
prependPlugins, appendPlugins	Differs: The official docs and the program disagree. The row says how. Docs say user or managed scope. The schema says managed only. Managed Only: Works only in managed (organization policy) settings.	Plugin ids that run before or after user mods.	Only these can call next.to. Rows: Hooks, Plugins, and Skills Settings.	Managed settings.
disableSideloadFlags	Documented: An official docs page names this item. Managed Only: Works only in managed (organization policy) settings.	Rejects --plugin-dir and --plugin-url.	Row: Hooks, Plugins, and Skills Settings.	Managed settings.
--safe-mode, --bare	Documented: An official docs page names this item.	No installed hooks module loads.	The program says: installed plugins are disabled, none of their hooks or hooks modules load, built-in plugins load regardless.	CLI flags.
Rollout switch	Gated: Works only behind a flag or a server gate. Remote flag, name not shown in the program strings	Installed hooks modules wait for a rollout flag. A message says installed mods are turned off remotely.	Built-in plugins and organization plugins load regardless.	Installed plugins.
CLAUDE_CODE_PLUGIN_DIRS, CLAUDE_CODE_PLUGIN_DIR_WATCH	Documented: An official docs page names this item.	Load plugin dirs as --plugin-dir does. Reload on save in a non-interactive session.	None.	Environment.

Limits

Hooks and Mod API calls run under time and size limits. Claude Code skips a hook that is too slow.

Limit	Value
Own time of one hook for one event	10 seconds, or 50 milliseconds for a prompt.edit hook (the program sets it on the event)
A .catch handler	1 second
All session.end hooks together	1.5 seconds unless you change the SessionEnd hook budget
$.process.run	30 seconds by default, 10 minutes at most
$.model.complete maxTokens	1024 by default, up to 64,000 or the output limit of the model
$.fs.read and $.fs.write	4 MiB for one file
$.http.fetch body and response	4 MiB each, 30 seconds, 5 redirects
$.store	4 MiB of JSON in all
$.session.messages()	The newest 4,096 entries
$.ui.invalidate('ui.render')	10 redraws a second, or 30 in the terminal for the visible pane
$.ui.toast	4 seconds unless you pass timeoutMs
A pane that nobody asked for	Placed from 144 terminal columns, 110 after the person opened it once
Names of commands, tools, subagent types, and panes	Letters, digits, _, and -, up to 64 characters
One claude plugin test test	5 seconds unless the test sets timeoutMs

Built-in Mods

Six built-in plugins ship in the program. The settings and flags that stop installed mods do not stop them.

Name in /plugin	What it does
cc-plugin-agents-md	Loads AGENTS.md as project instructions.
cc-plugin-diff	Takes over /diff and draws its pane.
cc-plugin-plugin-authoring	Gives Claude the plugin-authoring skill for writing mods. It holds no mod code.
cc-plugin-sec-default	Guards what your organization manages from the mods a user installs. You cannot turn it off.
cc-plugin-telemetry	Sends the analytics records that Claude Code and its built-in mods log.
cc-plugin-you-should-know	Displays a note above the prompt when a side agent finds something you might have missed. Off until you turn it on.

Related Pages

• Mod API Overview
• Hooks, on, and next