Claude Code Hooks Cookbook

Copy-paste Claude Code hooks that actually do something useful — auto-format on edit, block dangerous commands, notify you when a run finishes, gate on tests, and cut permission prompts. Every recipe is real, dependency-free, and current with the latest hook schema.

Hooks are shell commands Claude Code runs automatically at points in its loop — before a tool runs, after a file is edited, when a session starts, when the turn ends. They're how you turn "an agent that asks nicely" into "an agent that physically can't rm -rf your repo and always leaves the code formatted." Most examples online are stale; this repo tracks the current schema (the if: conditions, permissionDecision, updatedInput, and the full event list).

Quickstart

# drop the scripts into your project
git clone https://github.com/rongtnt/claude-code-hooks-cookbook /tmp/cc-hooks
mkdir -p .claude/hooks && cp /tmp/cc-hooks/hooks/* .claude/hooks/ && chmod +x .claude/hooks/*

Then add the recipes you want to .claude/settings.json (commit it to share with your team) or ~/.claude/settings.json (all projects, just you). Restart Claude Code or run /hooks to reload. That's it.

$CLAUDE_PROJECT_DIR is set by Claude Code to your project root, so the paths below work from any subdirectory.

Recipes

1. Auto-format on edit

Runs your formatter on any file Claude edits — Prettier / Ruff / rustfmt / gofmt / shfmt, whichever is installed. Note the ${tool_input.file_path} interpolation, so no stdin parsing is needed.

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
    "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-on-edit.sh",
      "args": ["${tool_input.file_path}"] } ] } ] } }

→ hooks/format-on-edit.sh

2. Block dangerous commands

A PreToolUse hook that returns a deny decision when a Bash command matches a destructive pattern (rm -rf, git push --force, disk writes, fork bombs, curl | sh). Claude gets told why and moves on.

{ "hooks": { "PreToolUse": [ { "matcher": "Bash",
    "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-commands.py" } ] } ] } }

→ hooks/block-dangerous-commands.py

Tip: you can also block without a script using the built-in if: condition — { "type": "command", "if": "Bash(rm *)", "command": "..." } — which only fires the hook when the command matches. The script version gives you finer control and a friendlier reason.

3. Protect secrets & path escapes

Denies edits to .env, *.pem, lockfiles, and anything resolving outside the project root — the two ways an agent quietly does damage.

{ "hooks": { "PreToolUse": [ { "matcher": "Edit|Write|MultiEdit",
    "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/protect-paths.py" } ] } ] } }

→ hooks/protect-paths.py

4. Gate on tests

On Stop, run the suite. If it's red, return {"decision":"block","reason":"..."} — Claude keeps fixing instead of declaring victory. Guards against infinite loops via stop_hook_active.

{ "hooks": { "Stop": [ { "hooks": [ { "type": "command",
    "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/test-gate.py", "timeout": 300 } ] } ] } }

→ hooks/test-gate.py (set TEST_CMD to your command)

5. Notify you

Desktop notification (macOS osascript / Linux notify-send) when Claude finishes or needs input, plus Slack if SLACK_WEBHOOK_URL is set. Never babysit a long run again.

{ "hooks": {
    "Notification": [ { "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.py" } ] } ],
    "Stop":         [ { "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.py", "args": ["done"] } ] } ] } }

→ hooks/notify.py

6. Inject repo context

A SessionStart hook that prepends live repo state — branch, uncommitted files, recent commits, open TODOs — so Claude starts oriented instead of re-discovering your repo every session.

{ "hooks": { "SessionStart": [ { "matcher": "startup|resume",
    "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/session-context.sh", "timeout": 10 } ] } ] } }

→ hooks/session-context.sh

7. Auto-approve read-only commands

Fast-tracks a tight allowlist of harmless commands (ls, cat, git status, rg…) with a permissionDecision: "allow", so you stop approving the obviously-safe ones. Never denies — unknown commands fall through to the normal flow.

{ "hooks": { "PreToolUse": [ { "matcher": "Bash",
    "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-approve-readonly.py" } ] } ] } }

→ hooks/auto-approve-readonly.py

8. Audit-log every tool call

A PostToolUse hook that appends one JSONL line per tool call to .claude/tool-log.jsonl — a cheap, greppable record of what the agent actually did.

{ "hooks": { "PostToolUse": [ { "matcher": "*",
    "hooks": [ { "type": "command",
      "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/log-tool-calls.py" } ] } ] } }

→ hooks/log-tool-calls.py

Cheat sheet

Events you'll actually use

There are ~30 events in total (task, worktree, permission, MCP-elicitation, file-watch…) — see the official reference.

Control flow

• Exit 0 → success. stdout is parsed as JSON for decision control.
• Exit 2 → blocking error. stderr is shown to Claude; the action is blocked (for blockable events). The simplest possible guardrail.
• Any other code → non-blocking; first line of stderr shows in the transcript, run continues.

Deny a tool (PreToolUse):

{ "hookSpecificOutput": { "hookEventName": "PreToolUse",
  "permissionDecision": "deny", "permissionDecisionReason": "why" } }

Force Claude to keep going (Stop / PostToolUse / UserPromptSubmit):

{ "decision": "block", "reason": "what still needs doing" }

Rewrite a tool's input before it runs (PreToolUse):

{ "hookSpecificOutput": { "hookEventName": "PreToolUse",
  "updatedInput": { "command": "npm run test:ci" } } }

Gotchas

• Hooks run with your shell and permissions — treat them like code you'd sudo. Only run scripts you've read.
• matcher is an exact string / A|B list, or a regex if it contains other characters (^Notebook, mcp__.*).
• PostToolUse fires after the tool already ran — it can add context or complain, but it can't un-ring the bell. Use PreToolUse to actually stop something.
• Blocking on Stop while your hook itself triggers more work can loop — gate on stop_hook_active (recipe 4 does).
• Config lives in .claude/settings.json (shared), .claude/settings.local.json (private), or ~/.claude/settings.json (global).

Contributing

Got a hook you actually use? PRs welcome — one recipe per PR, dependency-free if you can, and include the settings.json snippet. See CONTRIBUTING.md.

License

MIT — do whatever you want. If it saves you a 3am rm -rf, a ⭐ is appreciated.