hooks.json
A Claude Code settings key, read out of the shipped bundle. No mined inventory carries it: everything below comes from what this site has written about it.
Plugin validation now warns about symlinked or oversized files instead of reading them.
Not Anthropic's. This is the line from the earliest changelog entry here that named it, v2.1.233.
In the changelogs
20Releases whose published page names hooks.json.
-
v2.1.296
Warning about unknown keys in a plugin's hooks.json lists them differently
The warning about unknown keys in a plugin's
hooks.jsonno longer cuts the list off with "and N more"found in this entry's text
-
v2.1.296
Claude Code explains when a duplicate plugin's hooks do not run
When two plugins share a name, Claude Code now reports that the later one's hooks do not run or load
found in this entry's text
-
v2.1.281
Plugin hooks.json accepts a $schema key
A plugin's hooks.json file can now include a
$schemakey, which Claude Code ignores when loadingfound in this entry's text
-
v2.1.281
Hooks validation warns about unquoted plugin path placeholders (live)
Validating hooks.json now warns when a command hook uses a plugin path placeholder without quotes
found in this entry's text, named in this entry
-
v2.1.280
Plugin hooks manifest dedup warning for hooks/hooks.json
Claude Code now warns instead of double-loading a plugin's hooks.json if it's also listed explicitly
found in this entry's text
-
v2.1.275
Hooks modules must now be 'named like code'
Plugin hook modules must now use a recognized code file extension or they won't load
found in this entry's text, named in this entry
-
v2.1.269
hooks.json
surfacefield removed in favor of inline Client module referenceshooks.json drops its surface field; plugins now name their display module directly on each Client element
found in this entry's text
-
v2.1.269
Plugin loader: hook-module "surface" tagging removed; new parameter threaded through
Plugin hook loading drops an internal "surface" tag while gaining a new unused parameter
found in this entry's text
-
v2.1.268
Plugin skill/monitor path checks now surface unreadable-path errors instead of silently treating them as absent
Plugin loading now reports unreadable SKILL.md or monitors.json paths instead of treating them as missing
found in this entry's text
-
v2.1.267
Plugin hooks.json now warned on unknown/malformed keys
Claude Code now warns about unknown or malformed keys in a plugin's hooks.json
found in this entry's text
-
v2.1.267
New plugin "surface" UI system for terminal-rendered plugin components ("Clients")
Plugins can now draw their own interactive UI elements ('Clients') directly in the terminal
found in this entry's text
-
v2.1.267
hooks.json can now declare a
surfacemodulehooks.json can now declare a separate 'surface' module for drawing a hook module's UI elements
found in this entry's text
-
v2.1.265
Cursor IDE config import (
/import)/import can now bring in configuration from Cursor IDE, not just Codex and Gemini CLI
found in this entry's text
-
v2.1.257
Same top-level-hooks guard extended to plugin hooks.json files
A plugin hooks.json with permission hooks outside the hooks key now throws instead of loading malformed config.
named in this entry, found in this entry's text
-
v2.1.257
Hooks module scanning now flags PreToolUse/PermissionRequest declared outside the hooks object
Permission hooks declared at the top level of hooks.json now give a message pointing at the misconfiguration.
named in this entry, found in this entry's text
-
v2.1.242
/plugin validateinspects hooks modules instead of a declared capabilities listPlugin validation now loads your hooks modules and reports what they hook; the capabilities field is ignored.
found in this entry's text
-
v2.1.242
Plugin hooks modules: a JavaScript engine for plugin hooks, off unless enabled remotely
Plugin hooks.json gains a modules key for code-registered hooks, off unless enabled remotely.
found in this entry's text
-
v2.1.242
Plugins can ship JavaScript hook modules that run in a shared Bun worker, built but switched off
Plugins could ship JavaScript hook modules running in a worker, but loading is refused here.
found in this entry's text
-
v2.1.233
Plugin validation now reports symlinked and oversized files instead of reading them
Plugin validation now warns about symlinked or oversized files instead of reading them.
found in this entry's text
-
v2.1.77
Plugin/Skill Manifest Validation
found in this entry's text
First cited
8The earliest release whose published evidence quoted hooks.json was v2.1.233, 14 Aug 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
2 further spans in the ledger name it. The list above is the earliest first and stops at 6.
Presence across releases
0The miner has never read a build containing this name. It is here because a changelog entry of ours names it, which is evidence that it existed and not evidence of which releases carried it. The inventory starts at v2.1.138 and everything older than that was never mined.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the settings key does. All settings keys.