Hooks for Deterministic Automation

Everything you put in CLAUDE.md is advice. It is delivered to Claude as context — a polite, persistent note at the top of the conversation — and the model usually follows it. But "usually" is not "always." As the context window fills, as a session compacts, or simply because the rule got lost in a long file, Claude can quietly stop honoring an instruction. The docs are blunt about this: "If Claude keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost... convert it to a hook."

A hook is a guarantee. It is a shell command that Claude Code itself runs at a fixed point in the lifecycle — not something Claude chooses to do, but something the tool does, every time, with zero exceptions. The model's cooperation, memory, and attention are irrelevant: the script runs whether Claude is paying attention or not.

That single distinction drives every decision in this lesson:

The official guidance is a one-liner worth memorizing: use hooks for actions that must happen every time with zero exceptions. If forgetting the action would cost you — a missing format pass, a dangerous write, an unverified turn — it does not belong in a sentence. It belongs in a hook.

A hook is the pairing of an event (when it fires) with a command (what runs). Claude Code emits events at lifecycle points throughout a session; you register a command against the event you care about, optionally narrowed by a matcher so it only runs for specific tools.

Claude Code emits many events across the session lifecycle — the ones below are the most commonly used. For the complete, authoritative list, see the hooks reference documentation.

The events you can hook:

PreToolUse and PostToolUse are the workhorses — they bracket every tool call, so they're where "do X after every edit" and "never let Y happen" live. A matcher lets you scope them: a PostToolUse hook can match only Edit/Write events so it doesn't fire after a read.

Stop is the verification hook. When Claude decides its work "looks done" and tries to end the turn, a Stop hook runs your check (tests, a build, a script) and can block the turn from ending until the check passes — turning Claude back to keep working. This isn't unbounded: to prevent an infinite loop, Claude Code itself force-ends the turn after a fixed number of consecutive blocks. This is a hard limit enforced by the tool, not something the model can negotiate or work around.

Setup is special: it carries two matchers, init and maintenance, so the same event can distinguish a first-time bootstrap from a periodic upkeep run. You trigger these from the CLI (next section).

Hooks live in .claude/settings.json under a top-level hooks key, organized by event name. Each entry pairs an optional matcher with one or more shell commands to run.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\"" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/block-migrations.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "npm test" }
        ]
      }
    ]
  }
}

Two ways to author them:

• Let Claude write the hook. This is the documented fast path — try prompts like "Write a hook that runs eslint after every file edit" or "Write a hook that blocks writes to the migrations folder." Claude generates the JSON and the script.
• Edit .claude/settings.json by hand for full control over matchers and commands.

To see what's currently wired up, run /hooks — it browses every configured hook so you can confirm a hook is active (and catch one you forgot you added). Because hooks are part of settings, they follow the normal settings precedence (project .claude/settings.local.json overrides project .claude/settings.json overrides ~/.claude/settings.json), so you can keep a personal hook out of the shared, committed config.

Most hooks fire on their own as a session runs. Setup hooks are different — they exist to bootstrap or maintain a project's environment, and you invoke them explicitly from the CLI. Three flags drive them:

# First-time project bootstrap, then drop into a session
claude --init

# Bootstrap only — run setup hooks and exit (great for CI image prep)
claude --init-only

# Periodic maintenance run (fires Setup hooks matched to 'maintenance')
claude --maintenance

The init and maintenance matchers on the Setup event are what let one event serve two purposes: an init-matched Setup hook installs dependencies, scaffolds config, or seeds a database the first time; a maintenance-matched Setup hook re-runs upkeep (regenerate types, prune caches, refresh fixtures) on a schedule or in CI. Using --init-only in a container image build means the heavy setup happens once at build time, not on every session start.

Four patterns cover the vast majority of real-world hooks. Learn these and you'll recognize when a problem is really a hook in disguise.

1. Lint / format on edit — PostToolUse. The classic. After Claude edits or writes a file, run your formatter or linter so the result is always consistent — Claude never has to remember to format, because the tool does it.

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write",
  "hooks": [ { "type": "command", "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\"" } ] } ] } }

2. Block dangerous patterns — PreToolUse. Before a tool runs, inspect the proposed action and deny it if it crosses a line — writing to a migrations folder, touching a protected file, running a destructive command. The hook returns a non-zero / blocking result and the action never happens. "Write a hook that blocks writes to the migrations folder" is a documented example.

3. Run tests at turn end — Stop. Make a green test suite the condition for finishing. A Stop hook runs your tests when Claude tries to end its turn and blocks the stop until they pass, so Claude iterates until the suite is green. (Recall the hard limit: Claude Code itself force-ends the turn after a fixed number of consecutive blocks, so a permanently-failing test can't trap it forever — this is enforced by the tool, not a choice the model makes.)

4. Debug instruction loading — InstructionsLoaded. When you're not sure which CLAUDE.md, rule, or memory file is actually being loaded (or why a rule isn't taking effect), an InstructionsLoaded hook fires right after instructions load, letting you log or inspect the resolved set. It's the diagnostic counterpart to the four-tier CLAUDE.md hierarchy.

The pattern across all four: each replaces "I hope Claude remembers to..." with "the tool will always...".

Hooks matter most exactly when you are not watching. In an interactive session, you are the safety net — you see a bad edit and hit Esc. In a headless claude -p run, a CI job, a background agent, or an overnight fan-out, there is no human in the loop. Advice that Claude might forget is not good enough; you need guarantees that hold whether anyone is looking or not.

This is why the canonical unattended pattern is a Stop hook paired with real verification. Recall the core best practice: Claude stops when the work "looks done," and without a check, "looks done" is the only signal it has. A Stop hook supplies the missing check as a deterministic gate — it runs your tests/build/script and refuses to let the turn end until the check actually passes. Combined with scoped permissions (--allowedTools, --max-turns, --max-budget-usd), it lets an automated run finish correctly rather than finish plausibly.

# Unattended run: a committed Stop hook runs the tests; Claude can't
# "finish" until they're green. Permissions are scoped for safety.
claude -p "implement the feature from PLAN.md" \
  --permission-mode dontAsk \
  --allowedTools "Edit" "Bash(npm test)" "Bash(git commit *)"

And hooks remain the right tool for hard prohibitions in automation, complementing deny permission rules. A PreToolUse hook can block a class of dangerous actions deterministically — and unlike a conversational "please don't," it cannot be compacted away or forgotten on turn 40 of an unattended run.

One guarantee no hook overrides: protected-path writes are never auto-approved (.git, .claude except its subdirectories, .npmrc, .gitconfig, shell rc files) — except under bypassPermissions. So even in an aggressive automation setup, those sensitive files keep their prompt unless you have explicitly chosen to skip all checks in a throwaway container.