claude-code-hooks

Claude Code Hooks

Execute custom scripts before/after Claude Code tool invocations.

Quick Reference

| Event | When | Has Matcher | |-------|------|-------------| | PreToolUse | Before tool execution | Yes | | PostToolUse | After tool completes | Yes | | PermissionRequest | Permission dialog shown | Yes | | Notification | Notifications sent | Yes | | UserPromptSubmit | User submits prompt | No | | Stop | Agent finishes | No | | SubagentStop | Subagent finishes | No | | PreCompact | Before context compaction | No | | SessionStart | Session begins/resumes | No | | SessionEnd | Session ends | No |

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

| Pattern | Matches | |---------|---------| | "Write" | Only Write tool | | "" or "" | All tools | | "mcp__" | All MCP tools | | "Bash" | Bash commands |

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

| Use Case | Event | Example | |----------|-------|---------| | Validate inputs | PreToolUse | Block dangerous commands | | Audit logging | PostToolUse | Log all tool usage | | Custom approval | PermissionRequest | Slack notification | | Session init | SessionStart | Load project context |

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