D3 · Claude Code › Cluster 6 · Hooks

6.2 · Hook Configuration & Matchers

Wiring hooks in settings.json

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:

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.

🔑 For tool events (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:

LocationScopeShareable?
~/.claude/settings.jsonAll your projectsNo — local to your machine
.claude/settings.jsonThis projectYes — commit to the repo
.claude/settings.local.jsonThis projectNo — gitignored
Managed policy settingsOrganization-wideYes — admin-controlled
Run /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

flowchart TD ROOT["settings.json"] --> H["hooks {}"] H --> E1["PreToolUse (event key)"] H --> E2["PostToolUse (event key)"] E1 --> G1["group: matcher = 'Edit|Write'"] G1 --> HK1["hooks[]: { type:'command', command:'…' }"] E2 --> G2["group: matcher = 'Bash'"] G2 --> HK2["hooks[]: { type:'command', command:'…' }"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; class ROOT ok; class HK1 gate; class HK2 gate;

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" }
        ]
      }
    ]
  }
}
🔑 When several hooks match one event, they all run in parallel and every result is merged — so the log hook above runs even if the guard hook denies. Never rely on one hook to suppress another's side effects.

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 Read or Bash

⚠️ Empty / "*" matcher

  • Fires on every occurrence of the event
  • Fine for logging; wasteful (and risky) for anything heavier
  • For per-argument filtering, the if field beats a broad matcher

EXAM TRAPS

Trap: Putting command directly under the event key. → Wrong shape. It's event → [ { matcher, hooks: [ { type, command } ] } ]. There are two "hooks" levels.
Trap: "The matcher is a filename glob." → For tool events it matches the tool name (regex, case-sensitive), like Bash or Edit|Write — not the file path.
Trap: Editing a hook through the /hooks menu. → That menu is read-only. Edit the settings JSON (or ask Claude); /hooks only browses.
Trap: Expecting sibling hooks to run in sequence. → Matching hooks run in parallel and outputs are merged. Don't assume ordering between them.

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.