Hooks and Deterministic Automation

What it takes off your plate: removing "every time" from the model's free will

First thing that runs: auto-format after every edit

The official guide gives this verbatim. Drop it into .claude/settings.json at the project root and Prettier runs every time Claude finishes an Edit or Write:

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Event data arrives as JSON on stdin, which is why every official Bash example reaches for jq (brew install jq / apt-get install jq). When not to write this one: if the file can also be rewritten by a Bash command, the Edit|Write matcher misses it — the docs point you at a FileChanged hook watching the filename instead.

Second: block what must not be touched

Save this as .claude/hooks/protect-files.sh (remember chmod +x) and register it on PreToolUse as "$CLAUDE_PROJECT_DIR"/.claude/hooks/protect-files.sh:

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# On a match, exit 2: the action is blocked, stderr goes back as feedback
case "$FILE_PATH" in
  *.env|*/secrets/*) echo "Protected path, writes are denied" >&2; exit 2 ;;
esac
exit 0

Third: skip the writing, install the official one

/plugin install security-guidance@claude-plugins-official
# If the marketplace is not found, add it first:
/plugin marketplace add anthropics/claude-plugins-official

security-guidance is the one official plugin built entirely on hooks; once installed there is nothing to invoke. What it takes off your plate: injection, unsafe deserialization, dangerouslySetInnerHTML and friends move from "caught at PR review" to "caught as the line is written." When not to install it: it adds a model call on every turn that changed files and a deeper agentic review on every commit (Claude Opus 4.7 by default) — that is real money; outside a git repository the last two layers silently skip; cloud sessions do not load plugins at all. If the cost bites, keep only the free layer: ENABLE_CODE_SECURITY_REVIEW=0 turns off every model-backed review and leaves the pure string-match per-edit check.

Mechanism: 33 events × 5 types × 3 exit codes

Events: there is more than Pre/Post ToolUse

The event table in the official reference now lists 33 entries. The "13 lifecycle events" you see in community write-ups is stale. A few that get overlooked and shouldn't:

Types: five of them, and the last two are anti-deterministic

• command — run a shell command. Default timeout 10 minutes.
• http — POST to an endpoint; the same JSON comes back in the response body. $VAR in headers resolves only for names listed in allowedEnvVars.
• mcp_tool — call a tool on a configured MCP server directly.
• prompt — hand the event data to a model (Haiku by default) for a {"ok": true/false, "reason": "..."} verdict. 30-second timeout.
• agent — spawn a subagent that can read files and run commands before deciding. 60-second timeout, up to 50 tool turns. Marked experimental; the docs say prefer command for production.

Exit codes: only three cases

0 = success; stdout is parsed as JSON (and treated as plain text if it isn't, which some events inject into Claude's context). 2 = block, with stderr as the reason — but only on blockable events (PreToolUse, UserPromptSubmit, Stop, SubagentStop, PreModelSwitch and a few more); SessionStart and friends cannot be blocked, so exit 2 there merely shows stderr to you. Anything else = non-blocking error: the action proceeds and a hook error notice appears in the transcript.

Where the config lives decides who is governed

/hooks browses every configured hook grouped by event — but it is read-only; adding and removing means editing the JSON. The global off switch is "disableAllHooks": true, and administrators have allowManagedHooksOnly, which disables your own hooks and runs only the managed ones.

Copy a real registry

security-guidance splits itself into five registrations. This table is worth memorizing as a template (the source is on GitHub: .claude-plugin/ + hooks/ + tests/):

Three things to steal outright: put the expensive layer last (free string matching per edit, paid model review on Stop and commit); baseline first, verdict later (UserPromptSubmit snapshots, Stop diffs); and the reviewer is not the instance that wrote the code (a separate call with a fresh context).

Real usage and limits: six things you can install or read

① GowayLee/cchooks · Python SDK (132★)

pip install cchooks   # or: uv add cchooks

from cchooks import create_context, PreToolUseContext
c = create_context()
assert isinstance(c, PreToolUseContext)
if c.tool_name == "Write" and ".env" in c.tool_input.get("file_path", ""):
    c.output.exit_deny("Nope! .env files are protected")
else:
    c.output.exit_success()

Kills: hand-rolled json.load(sys.stdin) and memorized exit-code semantics; each event becomes a typed context object. Covers 9 events. When not to install: if your hook is a one-liner jq | xargs, a dependency is not worth it — and 9 events is far short of the current 33, so anything exotic goes back to raw parsing. (Per the GitHub repo page, 2026-09.)

② syou6162/cchook · YAML instead of JSON (34★)

go install github.com/syou6162/cchook@latest

PostToolUse:
  - matcher: "Write|Edit"
    conditions:
      - type: file_extension
        value: ".go"
    actions:
      - type: command
        command: "gofmt -w {.tool_input.file_path}"

Kills: the escaping hell inside settings.json; conditions (by extension, by pattern) become declarative, and it ships a dry-run mode. When not to install: the moment a team shares config, a non-official format is one more thing newcomers cannot read — and the star count says it is still niche. (Per the GitHub repo page, 2026-09.)

③ johnlindquist/claude-hooks · TypeScript (393★)

npx claude-hooks   # generates .claude/hooks/index.ts; execution needs Bun

Kills: guessing at payload shapes — you get typed payloads with autocomplete, all events dispatched from one index.ts. When not to install: it binds your runtime to Bun, so on CI or a teammate's machine without Bun the hook fails silently — and a failing hook is non-blocking by default, so without debug logging you never find out. (Per the GitHub repo page, 2026-09.)

④ disler/claude-code-hooks-mastery · the teaching repo (3.9k★)

This repo implements every event of its day as an Astral uv single-file Python script, including transcript backups before PreCompact and intercepting subagent completion. Kills: the question "what does this event's JSON actually look like" — reading it beats grepping the docs. When not to install: it is a reference, not a product; the README claims 13 events while the official reference is now at 33, and copying the whole .claude directory drags in its output styles and status line too. (Per the GitHub repo page, 2026-09.)

⑤ disler/claude-code-hooks-multi-agent-observability · a dashboard (1.5k★)

It POSTs every event over HTTP to a Bun server that broadcasts over WebSocket to a Vue 3 client, so several concurrent agents become visible in real time. Kills: the blindness of "five agents are running and one is stuck." When not to install: it needs uv, Bun and a long-running server — overkill for one person in one session, and the official http hook type now POSTs to an endpoint natively, so wiring your own log service may be lighter than adopting this stack. (Per the GitHub repo page, 2026-09.)

⑥ pre-commit/pre-commit · the half that isn't inside Claude (15.6k★)

pre-commit (pip install pre-commit → pre-commit install, configured in .pre-commit-config.yaml) governs the moment of committing. It is not a substitute for Claude's hooks, it is the next leg of the relay: Claude hooks only cover what Claude does, and commits you type in your own shell are invisible to them (the docs say even a ! shell escape does not count). When not to install: solo work where every change goes through Claude — then you are running the same linters twice.

Three criteria for choosing among the above

1. Does it need judgment? No → a command hook. Yes, but the event data is enough → prompt. Only by reading the code → agent (knowing it is experimental).
2. What does one miss cost? Merely ugly (unformatted) → fix it in PostToolUse. An incident (a committed secret) → block it in PreToolUse with exit 2, because PostToolUse cannot undo anything.
3. Governing Claude or governing everyone? Claude only → Claude hooks. Every commit → pre-commit or CI. Both → write both, but have the Claude side call the same script; never maintain two copies of one rule.

Costs and alternatives: hooks throw nondeterminism out the front door, then let it back in

Five line items

• No sandbox. Official wording: A hook can read files, make network requests, modify your environment, and run arbitrary commands. The advice is to treat them like shell aliases and dotfiles — enable only what you understand. The dangerous part is that hooks hide well: a plugin's hooks/hooks.json, skill frontmatter and subagent frontmatter all carry them, so installing a plugin means accepting everything it registers.
• Failure is silent. Any exit code other than 0 or 2 is a non-blocking error and the action completes anyway. To see the whole picture you need claude --debug or /debug mid-session.
• if is best-effort, not a security boundary. A filter like if: "Bash(rm *)" runs the hook anyway when Claude Code cannot determine which commands the input runs. The docs say it plainly: hard allow/deny belongs to the permission system, not to a hook.
• Matcher coverage is an illusion. Edit|Write never sees a file written by Bash. For real coverage the docs give three routes: a Stop hook scanning git status --porcelain once per turn; also matching Bash|PowerShell; or a FileChanged hook on the file itself.
• Time budgets. All SessionEnd hooks share 1.5 seconds (raised to at most 60 only if you set a longer explicit timeout). Read that before planning cleanup or log uploads there.

What to do instead of a hook

1. The permission system. When the rule is "must never touch this" rather than "log it if touched," allow/deny rules are the hard boundary.
2. pre-commit or CI. When the thing to govern is everyone's commits rather than Claude's edits, the hook is at the wrong layer.
3. CLAUDE.md or a skill. When the rule needs understanding and give ("prefer tests for new code"), pinning it down turns it into noise — an alert that always fires is no alert.
4. Nothing. If it happens once a month, writing the hook costs more than a decade of doing it by hand.