CONCEPT The shape: event → matcher → hooks array
Hooks live under a top-level hooks object in a settings
file. The object is keyed by event name. Each event maps to an array of matcher
groups, and each group has two keys:
matcher— a string (usually a tool-name pattern) that decides which occurrences the group applies to. Omit it, or use""or"*", to match everything.hooks— an array of hook handlers. The common one is{ "type": "command", "command": "…" }, which runs a shell command.
So the nesting is: hooks → EventName → [{ matcher, hooks: [{ type, command }] }].
Note there are two levels named "hooks": the outer object, and the inner array of handlers inside each group.
PreToolUse, PostToolUse), the
matcher is tested against the tool name — e.g. Bash, or the alternation
Edit|Write. It is a regex-style match and is case-sensitive. MCP tools use the
name form mcp__<server>__<tool>, so a pattern like mcp__github__.*
targets one server.CONCEPT Where you put it decides scope
The same hook block behaves differently depending on which settings file holds it:
| Location | Scope | Shareable? |
|---|---|---|
~/.claude/settings.json | All your projects | No — local to your machine |
.claude/settings.json | This project | Yes — commit to the repo |
.claude/settings.local.json | This project | No — gitignored |
| Managed policy settings | Organization-wide | Yes — admin-controlled |
/hooks to browse every configured hook grouped by event. The
/hooks menu is read-only — to add or change a hook, edit the JSON directly (or
ask Claude to). Set "disableAllHooks": true to turn them all off.DIAGRAM The config tree
CODE A realistic settings.json hooks block
Format after edits, and log every Bash command. Note the $CLAUDE_PROJECT_DIR variable, which
resolves to the project root so script paths work regardless of the current directory.
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command",
"command": "jq -r .tool_input.command >> ~/.claude/bash.log" },
{ "type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh" }
]
}
]
}
}
TRADE-OFFS Specific matcher vs. match-everything
✅ Specific matcher (e.g. Edit|Write)
- Hook fires only when relevant — no wasted processes
- Intent is obvious to the next reader
- Formatter doesn't run after a
ReadorBash
⚠️ Empty / "*" matcher
- Fires on every occurrence of the event
- Fine for logging; wasteful (and risky) for anything heavier
- For per-argument filtering, the
iffield beats a broad matcher
EXAM TRAPS
command directly under the event key. → Wrong shape. It's
event → [ { matcher, hooks: [ { type, command } ] } ]. There are two "hooks" levels.Bash or Edit|Write — not the file path./hooks menu. → That menu is
read-only. Edit the settings JSON (or ask Claude); /hooks only browses.PRACTICE
Q1 · Write a matcher that runs only after Edit and Write tools.
"matcher": "Edit|Write" under the PostToolUse event. The alternation
matches either tool name; it's case-sensitive.
Q2 · You commit .claude/settings.json with a hook. Who gets it?
Every teammate who clones the repo — project settings.json is
shareable. For a machine-local, gitignored hook use .claude/settings.local.json; for all
of your own projects use ~/.claude/settings.json.
Q3 · How do you disable all hooks without deleting them?
Set "disableAllHooks": true in the settings file. Browse what's active any time
with the /hooks menu.