Claude Code Hooks Cheat Sheet

Copy-paste patterns. Zero fluff. Official docs

How Hooks Work

Block Patterns

Block a specific command BLOCK

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
[ -z "$COMMAND" ] && exit 0
if echo "$COMMAND" | grep -qE 'rm\s+.*-rf\s+/'; then
  echo "BLOCKED: rm -rf on root" >&2
  exit 2
fi
exit 0Copy

Block file edits to specific paths BLOCK

#!/bin/bash
FILE=$(cat | jq -r '.tool_input.file_path // empty' 2>/dev/null)
[ -z "$FILE" ] && exit 0
case "$FILE" in
  */.env*|*/.ssh/*|*/.aws/*|*/credentials*)
    echo "BLOCKED: Protected file" >&2; exit 2 ;;
esac
exit 0Copy

Block git push to main BLOCK

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
[ -z "$COMMAND" ] && exit 0

# git takes its own options BEFORE the verb, so `git -C /repo push --force` does
# exactly what the plain form does while `git\s+push` never sees it. Strip the
# options first and every rule below can assume the verb sits next to `git`.
CHECK=$(printf '%s' "$COMMAND" | sed -E ':a;
  s/(^|[;&|[:space:]])git[[:space:]]+((-C|-c)[[:space:]]+[^[:space:]]+|--(git-dir|work-tree|namespace|exec-path)=[^[:space:]]+|--(no-pager|paginate|bare))[[:space:]]+/\1git /g; ta')

# [^;&|]* keeps each scan inside the push itself.
if printf '%s' "$CHECK" | grep -qE 'git\s+push\b[^;&|]*\b(main|master)\b'; then
  echo "BLOCKED: Direct push to main" >&2; exit 2
fi
# Bundled short flags (`-uf`) are a force-push too.
if printf '%s' "$CHECK" | grep -qE 'git\s+push\b[^;&|]*(--force\b|--force-with-lease\b|[^A-Za-z0-9]-[a-zA-Z]*f\b)'; then
  echo "BLOCKED: Force push" >&2; exit 2
fi
exit 0Copy

Block destructive git when dirty BLOCK

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
[ -z "$COMMAND" ] && exit 0
echo "$COMMAND" | grep -qE 'git\s+(checkout\s+--|reset\s+--hard|clean\s+-f)' || exit 0
DIRTY=$(git status --porcelain 2>/dev/null)
if [ -n "$DIRTY" ]; then
  echo "BLOCKED: Uncommitted changes would be lost" >&2; exit 2
fi
exit 0Copy

Block commits with conflict markers BLOCK

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
echo "$COMMAND" | grep -qE 'git\s+commit' || exit 0
CONFLICTS=$(git diff --cached --name-only 2>/dev/null | while read f; do
  [ -f "$f" ] && grep -lE '^(<{7}|={7}|>{7})' "$f" 2>/dev/null
done)
if [ -n "$CONFLICTS" ]; then
  echo "BLOCKED: Conflict markers in staged files" >&2; exit 2
fi
exit 0Copy

Auto-Approve Patterns

Auto-approve safe commands APPROVE

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
[ -z "$COMMAND" ] && exit 0
if echo "$COMMAND" | grep -qE '^\s*(npm\s+test|cargo\s+test|go\s+test|pytest|make\s+test)'; then
  echo '{"decision":"approve","reason":"Safe test command"}'
  exit 0
fi
exit 0Copy

Auto-approve read-only git APPROVE

#!/bin/bash
COMMAND=$(cat | jq -r '.tool_input.command // empty' 2>/dev/null)
[ -z "$COMMAND" ] && exit 0
if echo "$COMMAND" | grep -qE '^\s*git\s+(status|log|diff|show|branch|remote|tag\s+-l)'; then
  echo '{"decision":"approve","reason":"Read-only git"}'
fi
exit 0Copy

Monitor Patterns

Log all tool calls MONITOR

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // .tool_input.file_path // ""' 2>/dev/null)
echo "[$(date -Iseconds)] $TOOL: $CMD" >> ~/.claude/tool-calls.log
exit 0Copy

Warn on large output WARN

#!/bin/bash
OUTPUT=$(cat | jq -r '.tool_result // empty' 2>/dev/null)
LEN=${#OUTPUT}
if [ "$LEN" -gt 50000 ]; then
  echo "WARNING: Output is ${LEN} chars — consuming context fast" >&2
fi
exit 0Copy

Desktop notification on session end MONITOR

#!/bin/bash
# TRIGGER: Stop  MATCHER: ""
MSG=$(cat | jq -r '.stop_reason // "completed"' 2>/dev/null)
notify-send "Claude Code" "Session $MSG" 2>/dev/null ||     # Linux
osascript -e "display notification \"$MSG\"" 2>/dev/null     # macOS
exit 0Copy

settings.json Reference

Minimal setup (one hook)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash ~/.claude/hooks/my-guard.sh"
      }]
    }]
  }
}Copy

Multiple hooks on different triggers

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {"type":"command","command":"bash ~/.claude/hooks/destructive-guard.sh"},
          {"type":"command","command":"bash ~/.claude/hooks/branch-guard.sh"}
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {"type":"command","command":"bash ~/.claude/hooks/scope-guard.sh"}
        ]
      }
    ],
    "PostToolUse": [{
      "matcher": "",
      "hooks": [{"type":"command","command":"bash ~/.claude/hooks/monitor.sh"}]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{"type":"command","command":"bash ~/.claude/hooks/notify.sh"}]
    }]
  }
}Copy

Debug Hooks

Test a hook manually

# Test PreToolUse hook with sample input
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | bash ~/.claude/hooks/my-guard.sh
echo "Exit code: $?"Copy

Check hook is executable

ls -la ~/.claude/hooks/
# Fix: chmod +x ~/.claude/hooks/*.shCopy

Validate settings.json

python3 -c "import json; json.load(open('$HOME/.claude/settings.json')); print('Valid')"Copy

Quick health check

npx github:yurukusa/cc-safe-setup --quickfix   # Auto-detect and fix problems
npx github:yurukusa/cc-safe-setup --doctor     # Detailed diagnosis
npx github:yurukusa/cc-safe-setup --verify     # Test each hookCopy

Quick Recipes

Exit Code Reference