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_DIRfor 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-ops.md- Production security
See Also: claude-code-debug for troubleshooting, claude-code-headless for CLI automation