dwmkerr/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 - All events with input/output schemas
• Examples: Firewall - Block dangerous commands
• Examples: Quality Checks - Lint/format after edits
• Examples: Pre-Push Tests - 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

{
  "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

#!/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:

echo "[DEBUG] Hook triggered: $cmd" >> /tmp/hook-debug.log

Attribution

Examples adapted from Steve Kinney's Claude Code Hook Examples.