claude-code-hook-development

# Claude Code Hook Development Create hooks that run shell commands on specific events to add guardrails, automations, and policy enforcement. ## Quick Reference You MUST read the reference files for detailed schemas and examples: - [Hook Events Reference](./references/hook-events.md) - All events with input/output schemas - [Examples: Firewall](./references/examples/firewall.md) - Block dangerous commands - [Examples: Quality Checks](./references/examples/quality-checks.md) - Lint/format after edits - [Examples: Pre-Push Tests](./references/examples/pre-push-tests.md) - Run tests before git push ## Core Concepts ### Hook Types 1. **Command hooks** - Run bash scripts 2. **Prompt hooks** - Query LLM for context-aware decisions ### Exit Codes | Code | Meaning | Behavior | |------|---------|----------| | 0 | Success | Action proceeds; stdout shown in verbose mode | | 2 | Block | Action blocked; stderr fed to Claude | | Other | Error | Non-blocking; stderr shown to user | ### File Locations - Settings: `.claude/settings.json` - Scripts: `.claude/hooks/` (mark executable) ## Settings Structure ```json { "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": ".claude/hooks/my-script.sh", "timeout": 60 } ] } ] } } ``` ## Hook Events Summary | Event | When | Can Block? | |-------|------|------------| | PreToolUse | Before tool executes | Yes (exit 2) | | PostToolUse | After tool completes | Feedback only | | PermissionRequest | User sees permission dialog | Yes | | UserPromptSubmit | User submits prompt | Yes | | Stop | Main agent finishes | Yes (continue) | | SubagentStop | Subagent finishes | Yes (continue) | | SessionStart | Session begins | Add context | | SessionEnd | Session ends | Cleanup only | | Notification | Notifications sent | No | | PreCompact | Before compact | No | ## Common Matchers For PreToolUse/PostToolUse/PermissionRequest: - `Bash` - Shell commands - `Edit`, `Write`, `Read` - File operations - `Glob`, `Grep` - Search operations - `Task` - Subagent tasks - `mcp__<server>__<tool>` - MCP tools - Regex patterns supported ### Wildcard Permissions Use wildcards for flexible matching patterns: - `Bash(npm *)` - Match any npm command - `Bash(*-h*)` - Match commands containing `-h` - `Bash(git:*)` - Match any git subcommand This reduces configuration overhead and avoids mismatched permissions blocking legitimate workflows. ## Script Template ```bash #!/usr/bin/env bash set -euo pipefail # Read JSON input input=$(cat) tool_name=$(echo "$input" | jq -r '.tool_name // ""') command=$(echo "$input" | jq -r '.tool_input.command // ""') # Your validation logic here if [[ "$command" =~ dangerous_pattern ]]; then echo "Blocked: reason here" >&2 exit 2 fi exit 0 ``` ## Critical: Activating Hook Changes Hooks are **snapshotted at startup**. After creating or modifying hooks: > **⚠️ Changes won't take effect until you either:** > 1. **Restart Claude Code** (exit and re-run `claude`), OR > 2. **Run `/hooks`** to review and apply the updated configuration > > This is a security feature - it prevents malicious hook modifications from affecting your current session. ### Verifying Hooks Are Loaded After restart, run `/hooks` to confirm your hook appears in the list. If it doesn't show up: - Check JSON syntax in settings file - Verify file is in correct location (`.claude/settings.json`) - Look for `disableAllHooks: true` in any settings file ## Troubleshooting ### Hook Not Triggering 1. **Did you restart?** Hooks are snapshotted at startup - run `/hooks` or restart Claude Code 2. **Check `/hooks` output** - Your hook should be listed with correct matcher 3. **Validate JSON** - Run `cat .claude/settings.json | jq .` to check syntax 4. **Check matcher** - Tool names are case-sensitive (`Bash` not `bash`) ### Testing Hooks Safely When creating hooks that block operations (like preventing push to main): 1. **Test on a safe branch first** - Modify the hook to block a test branch 2. **Verify the block works** - Attempt the blocked operation 3. **Update to production config** - Change to block the actual target (e.g., main) 4. **Restart and verify** - Run `/hooks` to confirm the updated hook is loaded ### Debugging Use `claude --debug` to see hook execution details, or add logging to your hook: ```bash echo "[DEBUG] Hook triggered: $cmd" >> /tmp/hook-debug.log ``` ## Attribution Examples adapted from [Steve Kinney's Claude Code Hook Examples](https://stevekinney.com/courses/ai-development/claude-code-hook-examples).