Hook Authoring

Hook Authoring — Official Best Practices

What Hooks Do

Hooks are deterministic shell commands (or LLM prompts) that execute at specific lifecycle points. They provide guaranteed behavior — not relying on the LLM to choose to run them.

Configuration Locations

Hook Types

Hook Events

See quick-ref/events-reference.md for full input/output schemas.

*PostToolUse Stop hooks can return {"decision": "block"} to keep Claude working.

Configuration Format

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

Input/Output Protocol

Input (stdin JSON)

Every hook receives JSON on stdin with common fields + event-specific data:

{
  "session_id": "abc123",
  "cwd": "/path/to/project",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test" }
}

Output (exit codes)

Structured JSON output (exit 0 + JSON on stdout)

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep"
  }
}

PreToolUse decisions: "allow", "deny", "ask".

Common Patterns

Auto-format after edits

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

Block protected files

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE" == *"$pattern"* ]]; then
    echo "Blocked: matches protected pattern '$pattern'" >&2
    exit 2
  fi
done
exit 0

Re-inject context after compaction

{
  "SessionStart": [{
    "matcher": "compact",
    "hooks": [{ "type": "command", "command": "echo 'Reminder: use Bun, not npm. Run tests before commits.'" }]
  }]
}

Notification on idle

{
  "Notification": [{
    "matcher": "",
    "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'" }]
  }]
}

Stop Hook Infinite Loop Prevention

Always check stop_hook_active to avoid loops:

INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Let Claude stop
fi
# ... your logic

Anti-Patterns

Checklist

• Correct event chosen for the use case
• Matcher pattern tested (case-sensitive, regex)
• Script is executable (chmod +x)
• Uses jq for JSON parsing (or Python/Node)
• Exit code 2 for blocking, 0 for allowing
• Stop hooks check stop_hook_active
• Tested with sample JSON piped to stdin
• Hook script uses absolute paths or $CLAUDE_PROJECT_DIR

Reference

• All events with input/output schemas
• Hook types comparison