Claude Code Hooks

Execute custom scripts before/after Claude Code tool invocations.

Quick Reference

Basic Configuration

Add to ~/.claude/settings.json or .claude/settings.local.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/hooks/validate.sh",
        "timeout": 5000
      }]
    }]
  }
}

Matcher Patterns

Hook Script Requirements

#!/bin/bash
# Receives JSON via stdin: { "tool_name": "...", "tool_input": {...} }
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')

# Exit codes:
# 0 = Success (continue)
# 2 = Block with error (stderr shown to Claude)
# Other = Non-blocking error

Common Use Cases

Security Checklist

• Quote all variables: "$VAR" not $VAR
• Validate paths (no .. traversal)
• Use $CLAUDE_PROJECT_DIR for paths
• Set reasonable timeouts
• Handle jq parsing errors

Troubleshooting

# Debug hook loading
claude --debug

# List registered hooks
/hooks

# Test script manually
echo '{"tool_name":"Bash"}' | ./hooks/validate.sh

Official Documentation

• https://code.claude.com/docs/en/hooks - Hooks reference
• https://code.claude.com/docs/en/settings - Settings configuration

Additional Resources

• ./references/hook-events.md - All events with input/output schemas
• ./references/configuration.md - Advanced config patterns
• ./references/security-patterns.md - Production security

See Also: claude-code-debug for troubleshooting, claude-code-headless for CLI automation