15 - Hooks: Event-Driven Automation in Claude Code

┌──────────────────────┐
│    Trigger Event     │
│  (e.g. PreToolUse)   │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   Input Preparation  │
│  (JSON via stdin)    │
│  - tool_name         │
│  - tool_input        │
│  - session_id        │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Command Execution   │  ← User-defined shell script
│  (shell command)     │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│   Output Processing  │
│  (JSON via stdout)   │
│  - decision: allow   │
│  - decision: block   │
│  - decision: modify  │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│  Flow Continuation   │
│  Claude Code         │
└──────────────────────┘

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "/path/to/script.sh"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 /path/to/logger.py"
      }
    ],
    "Stop": [
      {
        "command": "notify-send 'Claude Code' 'Task completed!'"
      }
    ]
  }
}

// Single tool
"matcher": "Write"

// Multiple tools with OR
"matcher": "Write|Edit|MultiEdit"

// Complex regex pattern
"matcher": "^(Bash|Terminal)$"

// All tools (no matcher = wildcard)
// Omit the matcher field

// Tools starting with "File"
"matcher": "^File.*"

// Exclude specific tools (regex negation)
"matcher": "^(?!Read).*$"

#!/bin/bash
# PreToolUse hook: block operations on protected files

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
TOOL_INPUT=$(echo "$INPUT" | jq -r '.tool_input')

# Block writing to critical configuration files
if [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ]; then
  FILE_PATH=$(echo "$TOOL_INPUT" | jq -r '.file_path // .path // ""')

  # Protected files list
  PROTECTED_FILES=(".env" ".env.production" "secrets.json" "credentials.yaml")

  for PROTECTED in "${PROTECTED_FILES[@]}"; do
    if [[ "$FILE_PATH" == *"$PROTECTED"* ]]; then
      echo "{\"decision\": \"block\", \"reason\": \"Protected file: $PROTECTED. Manual modification required.\"}"
      exit 0
    fi
  done
fi

# Block destructive Bash commands
if [ "$TOOL_NAME" = "Bash" ]; then
  COMMAND=$(echo "$TOOL_INPUT" | jq -r '.command // ""')

  # Dangerous patterns
  if echo "$COMMAND" | grep -qE "rm\s+-rf\s+/|DROP\s+TABLE|DELETE\s+FROM.*WHERE\s+1=1|format\s+c:"; then
    echo "{\"decision\": \"block\", \"reason\": \"Potentially destructive command blocked.\"}"
    exit 0
  fi
fi

# Allow everything else
echo '{"decision": "allow"}'

#!/bin/bash
# PreToolUse hook: automatically adds headers to new files

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "Write" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content')

  # Add copyright header to TypeScript files
  if [[ "$FILE_PATH" == *.ts ]]; then
    HEADER="// Copyright $(date +%Y) - MyCompany\n// Auto-generated header by Claude Code hook\n\n"
    MODIFIED_CONTENT="${HEADER}${CONTENT}"

    echo "$INPUT" | jq --arg content "$MODIFIED_CONTENT" \
      '{decision: "modify", tool_input: (.tool_input + {content: $content})}'
    exit 0
  fi
fi

echo '{"decision": "allow"}'

#!/usr/bin/env python3
"""PostToolUse hook: logs all file write operations."""

import json
import sys
from datetime import datetime
from pathlib import Path

def main():
    input_data = json.loads(sys.stdin.read())

    tool_name = input_data.get("tool_name", "")
    tool_input = input_data.get("tool_input", {})
    session_id = input_data.get("session_id", "unknown")

    # Log only file modification operations
    if tool_name in ("Write", "Edit", "MultiEdit"):
        log_entry = {
            "timestamp": datetime.now().isoformat(),
            "session_id": session_id,
            "tool": tool_name,
            "file": tool_input.get("file_path", "N/A"),
            "operation": "write" if tool_name == "Write" else "edit"
        }

        log_file = Path(".claude/hooks/activity.log")
        log_file.parent.mkdir(parents=True, exist_ok=True)

        with open(log_file, "a") as f:
            f.write(json.dumps(log_entry) + "\n")

    # Log executed Bash commands
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        log_entry = {
            "timestamp": datetime.now().isoformat(),
            "session_id": session_id,
            "tool": "Bash",
            "command": command[:200],  # Truncate for safety
            "exit_code": "success"
        }

        log_file = Path(".claude/hooks/bash-history.log")
        log_file.parent.mkdir(parents=True, exist_ok=True)

        with open(log_file, "a") as f:
            f.write(json.dumps(log_entry) + "\n")

if __name__ == "__main__":
    main()

#!/bin/bash
# UserPromptSubmit hook: adds automatic Git context

INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt')

# Add current branch information
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "N/A")
LAST_COMMIT=$(git log --oneline -1 2>/dev/null || echo "N/A")
DIRTY_FILES=$(git status --porcelain 2>/dev/null | wc -l)

# Create enriched context
CONTEXT="[Git Context: branch=$BRANCH, last_commit=$LAST_COMMIT, dirty_files=$DIRTY_FILES]"

# Modify the prompt by adding context
ENRICHED_PROMPT="$CONTEXT\n\n$PROMPT"

echo "$INPUT" | jq --arg prompt "$ENRICHED_PROMPT" \
  '{decision: "modify", prompt: $prompt}'

#!/bin/bash
# Stop hook: sends desktop notification when Claude completes

INPUT=$(cat)
STOP_REASON=$(echo "$INPUT" | jq -r '.stop_reason // "completed"')

# Notification on Linux (notify-send)
if command -v notify-send &> /dev/null; then
  notify-send "Claude Code" "Task completed: $STOP_REASON" \
    --icon=dialog-information \
    --urgency=normal
fi

# Notification on macOS (osascript)
if command -v osascript &> /dev/null; then
  osascript -e "display notification \"Task completed: $STOP_REASON\" with title \"Claude Code\""
fi

# Completion sound
if command -v aplay &> /dev/null; then
  aplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null &
elif command -v afplay &> /dev/null; then
  afplay /System/Library/Sounds/Glass.aiff &
fi

#!/bin/bash
# SessionStart hook: prepares the development environment

# Verify prerequisites
echo "Verifying development environment..." >&2

# Check that Node.js is available
if ! command -v node &> /dev/null; then
  echo '{"warning": "Node.js not found. Some features may not work."}' >&2
fi

# Check that the development database is reachable
if command -v pg_isready &> /dev/null; then
  if ! pg_isready -q 2>/dev/null; then
    echo '{"warning": "PostgreSQL not reachable. Start the database."}' >&2
  fi
fi

# Load environment variables from .env
if [ -f ".env" ]; then
  export $(grep -v '^#' .env | xargs) 2>/dev/null
fi

# Record session start
echo "{\"session_start\": \"$(date -Iseconds)\", \"cwd\": \"$(pwd)\"}" \
  >> .claude/hooks/sessions.log 2>/dev/null

# Clean up temporary files from previous sessions
find /tmp -name "claude-hook-*" -mtime +1 -delete 2>/dev/null

#!/usr/bin/env python3
"""SessionEnd hook: generates a work session report."""

import json
import sys
from datetime import datetime
from pathlib import Path

def main():
    input_data = json.loads(sys.stdin.read())
    session_id = input_data.get("session_id", "unknown")

    # Read the activity log
    log_file = Path(".claude/hooks/activity.log")
    activities = []
    if log_file.exists():
        with open(log_file) as f:
            for line in f:
                try:
                    entry = json.loads(line.strip())
                    if entry.get("session_id") == session_id:
                        activities.append(entry)
                except json.JSONDecodeError:
                    continue

    # Generate report
    report = {
        "session_id": session_id,
        "end_time": datetime.now().isoformat(),
        "total_operations": len(activities),
        "files_modified": list(set(
            a.get("file", "") for a in activities
            if a.get("tool") in ("Write", "Edit", "MultiEdit")
        )),
        "bash_commands": sum(
            1 for a in activities if a.get("tool") == "Bash"
        )
    }

    # Save report
    reports_dir = Path(".claude/hooks/reports")
    reports_dir.mkdir(parents=True, exist_ok=True)
    report_file = reports_dir / f"session-{session_id[:8]}.json"

    with open(report_file, "w") as f:
        json.dump(report, f, indent=2)

    print(f"Session report saved: {report_file}", file=sys.stderr)

if __name__ == "__main__":
    main()

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx britfix --auto-fix"
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "command": "cc-notify --channel slack --sound chime --message 'Task completed'"
      }
    ],
    "SessionStart": [
      {
        "command": "cc-notify --channel desktop --message 'Claude session started'"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "cc-notify --log-activity bash"
      }
    ]
  }
}

#!/usr/bin/env python3
"""Hook created with cchooks SDK."""

from cchooks import hook, PreToolUseInput, HookDecision

@hook("PreToolUse")
def validate_file_size(event: PreToolUseInput) -> HookDecision:
    """Block writing files that are too large."""

    if event.tool_name == "Write":
        content = event.tool_input.get("content", "")
        max_lines = 500

        if content.count("\n") > max_lines:
            return HookDecision.block(
                reason=f"File too large: {content.count(chr(10))} lines "
                       f"(max {max_lines}). Split into smaller files."
            )

    return HookDecision.allow()

@hook("PostToolUse")
def auto_lint(event):
    """Runs automatic linting after every file modification."""
    import subprocess

    if event.tool_name in ("Write", "Edit"):
        file_path = event.tool_input.get("file_path", "")

        if file_path.endswith(".ts") or file_path.endswith(".js"):
            subprocess.run(
                ["npx", "eslint", "--fix", file_path],
                capture_output=True, timeout=30
            )
        elif file_path.endswith(".py"):
            subprocess.run(
                ["python3", "-m", "black", file_path],
                capture_output=True, timeout=30
            )

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "claude-hook-comms publish --topic file-changes --data-from-stdin"
      }
    ],
    "SessionStart": [
      {
        "command": "claude-hook-comms subscribe --topic file-changes --handler sync-handler.sh"
      }
    ]
  }
}

// sync-handler.sh - Handles file change notifications
#!/bin/bash
INPUT=$(cat)
CHANGED_FILE=$(echo "$INPUT" | jq -r '.file_path')
AGENT_ID=$(echo "$INPUT" | jq -r '.agent_id')

echo "[SYNC] Agent $AGENT_ID modified: $CHANGED_FILE" >> .claude/hooks/sync.log

#!/bin/bash
set -euo pipefail

# Read JSON input from stdin
INPUT=$(cat)

# Extract common fields
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""')

# ================================
# HOOK LOGIC
# ================================

# Example: log the operation
echo "[$(date -Iseconds)] Hook triggered: tool=$TOOL_NAME session=$SESSION_ID" >&2

# ================================
# OUTPUT (only for PreToolUse/UserPromptSubmit)
# ================================

# Option 1: Allow
echo '{"decision": "allow"}'

# Option 2: Block
# echo '{"decision": "block", "reason": "Reason for blocking"}'

# Option 3: Modify
# echo '{"decision": "modify", "tool_input": {...}}'

#!/bin/bash
# Test a hook by simulating JSON input

HOOK_SCRIPT="./my-hook.sh"

# Simulate PreToolUse input for Write
echo '{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/tmp/test.ts",
    "content": "console.log(\"hello\");"
  },
  "session_id": "test-session-001"
}' | bash "$HOOK_SCRIPT"

echo "---"

# Simulate PreToolUse input for Bash with dangerous command
echo '{
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /"
  },
  "session_id": "test-session-001"
}' | bash "$HOOK_SCRIPT"

echo "---"

# Verify exit code
echo "Exit code: $?"

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash .claude/hooks/pre-tool-guard.sh"
      },
      {
        "matcher": "Bash",
        "command": "bash .claude/hooks/bash-validator.sh"
      }
    ],
    "PostToolUse": [
      {
        "command": "python3 .claude/hooks/post-tool-logger.py"
      }
    ],
    "Stop": [
      {
        "command": "bash .claude/hooks/notify-complete.sh"
      }
    ],
    "SessionStart": [
      {
        "command": "bash .claude/hooks/session-init.sh"
      }
    ],
    "SessionEnd": [
      {
        "command": "python3 .claude/hooks/session-report.py"
      }
    ]
  }
}

#!/bin/bash
# PostToolUse hook: creates automatic checkpoints

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

# Only for file modification operations
if [ "$TOOL_NAME" = "Write" ] || [ "$TOOL_NAME" = "Edit" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')

  # Check if there are enough changes for a checkpoint
  CHANGES=$(git diff --stat 2>/dev/null | tail -1)
  NUM_FILES=$(git diff --name-only 2>/dev/null | wc -l)

  if [ "$NUM_FILES" -ge 3 ]; then
    git add -A 2>/dev/null
    git commit -m "checkpoint: auto-save after $NUM_FILES files modified" \
      --no-verify 2>/dev/null
    echo "[CHECKPOINT] Automatic commit: $NUM_FILES files" >&2
  fi
fi

#!/bin/bash
# PreToolUse hook: quality gate for TypeScript files

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [ "$TOOL_NAME" = "Write" ]; then
  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path')
  CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content')

  if [[ "$FILE_PATH" == *.ts ]]; then
    # Write the content to a temporary file for analysis
    TEMP_FILE=$(mktemp /tmp/claude-hook-XXXXXX.ts)
    echo "$CONTENT" > "$TEMP_FILE"

    # Run type checking
    ERRORS=$(npx tsc --noEmit --strict "$TEMP_FILE" 2>&1 || true)

    rm -f "$TEMP_FILE"

    if echo "$ERRORS" | grep -q "error TS"; then
      ERROR_COUNT=$(echo "$ERRORS" | grep -c "error TS")
      echo "{\"decision\": \"block\", \"reason\": \"Type check failed: $ERROR_COUNT TypeScript errors found. Fix before writing.\"}"
      exit 0
    fi
  fi
fi

echo '{"decision": "allow"}'

#!/bin/bash
# UserPromptSubmit hook: context enrichment pipeline

INPUT=$(cat)
PROMPT=$(echo "$INPUT" | jq -r '.prompt')

# Gather context
CONTEXT_PARTS=()

# 1. Git state
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
if [ -n "$BRANCH" ]; then
  DIRTY=$(git status --porcelain 2>/dev/null | wc -l)
  CONTEXT_PARTS+=("[Branch: $BRANCH, Modified files: $DIRTY]")
fi

# 2. Recent failed tests
if [ -f "test-results.json" ]; then
  FAILED=$(jq '.numFailedTests // 0' test-results.json 2>/dev/null)
  if [ "$FAILED" -gt 0 ]; then
    CONTEXT_PARTS+=("[WARNING: $FAILED tests failed]")
  fi
fi

# 3. Pending TODOs
TODO_COUNT=$(grep -r "TODO\|FIXME\|HACK" src/ --include="*.ts" 2>/dev/null | wc -l)
if [ "$TODO_COUNT" -gt 0 ]; then
  CONTEXT_PARTS+=("[Open TODOs in code: $TODO_COUNT]")
fi

# Build aggregated context
if [ ${#CONTEXT_PARTS[@]} -gt 0 ]; then
  CONTEXT=$(printf "%s " "${CONTEXT_PARTS[@]}")
  ENRICHED="$CONTEXT\n\n$PROMPT"
  echo "$INPUT" | jq --arg p "$ENRICHED" '{decision: "modify", prompt: $p}'
else
  echo '{"decision": "allow"}'
fi

#!/bin/bash
set -euo pipefail

# Trap to handle errors and cleanup
cleanup() {
  local exit_code=$?
  if [ $exit_code -ne 0 ]; then
    echo "[HOOK ERROR] Exit code: $exit_code" >&2
    echo "{\"error\": \"Hook failed with code $exit_code\"}" >&2
  fi
  # Cleanup temporary resources
  rm -f /tmp/claude-hook-$$.tmp 2>/dev/null
}
trap cleanup EXIT

# Timeout for the entire script
TIMEOUT=10
(
  sleep $TIMEOUT
  echo "[HOOK TIMEOUT] Script exceeded $TIMEOUT seconds" >&2
  kill $$ 2>/dev/null
) &
TIMEOUT_PID=$!

# Main logic with error handling
INPUT=$(cat) || {
  echo '{"decision": "allow"}' # Safe fallback
  exit 0
}

TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null) || TOOL_NAME=""

# ... hook logic ...

# Cancel the timeout timer
kill $TIMEOUT_PID 2>/dev/null || true

echo '{"decision": "allow"}'

{
  "hooks": {
    "SessionStart": [
      {
        "command": "bash .claude/hooks/check-dependencies.sh",
        "timeout": 15000
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash .claude/hooks/validate-angular-conventions.sh",
        "timeout": 5000
      },
      {
        "matcher": "Bash",
        "command": "bash .claude/hooks/block-dangerous-commands.sh",
        "timeout": 3000
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "bash .claude/hooks/auto-lint-format.sh",
        "timeout": 10000
      },
      {
        "command": "python3 .claude/hooks/activity-tracker.py",
        "timeout": 5000
      }
    ],
    "UserPromptSubmit": [
      {
        "command": "bash .claude/hooks/enrich-with-project-context.sh",
        "timeout": 5000
      }
    ],
    "Stop": [
      {
        "command": "bash .claude/hooks/desktop-notification.sh"
      }
    ],
    "SessionEnd": [
      {
        "command": "python3 .claude/hooks/generate-session-report.py",
        "timeout": 10000
      }
    ]
  }
}

#!/bin/bash
# PreToolUse: validate Angular conventions for new files

INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')

# Verify naming convention for Angular components
if [[ "$FILE_PATH" == *.component.ts ]]; then
  # Check that the name follows kebab-case
  FILENAME=$(basename "$FILE_PATH" .component.ts)
  if ! echo "$FILENAME" | grep -qE '^[a-z][a-z0-9]*(-[a-z0-9]+)*$'; then
    echo "{\"decision\": \"block\", \"reason\": \"Naming convention violated: Angular components must use kebab-case. File: $FILENAME\"}"
    exit 0
  fi
fi

# Verify that service files are in the services/ directory
if [[ "$FILE_PATH" == *.service.ts ]] && [[ "$FILE_PATH" != */services/* ]]; then
  echo "{\"decision\": \"block\", \"reason\": \"Angular services must be in the services/ directory\"}"
  exit 0
fi

echo '{"decision": "allow"}'

#!/bin/bash
# Wrapper that adds debugging to any hook

HOOK_SCRIPT="$1"
LOG_DIR=".claude/hooks/logs"
mkdir -p "$LOG_DIR"

# Capture input
INPUT=$(cat)
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# Log input
echo "=== $TIMESTAMP ===" >> "$LOG_DIR/debug.log"
echo "Hook: $HOOK_SCRIPT" >> "$LOG_DIR/debug.log"
echo "Input: $INPUT" >> "$LOG_DIR/debug.log"

# Execute hook and capture output
OUTPUT=$(echo "$INPUT" | bash "$HOOK_SCRIPT" 2>> "$LOG_DIR/debug.log")
EXIT_CODE=$?

# Log output
echo "Output: $OUTPUT" >> "$LOG_DIR/debug.log"
echo "Exit: $EXIT_CODE" >> "$LOG_DIR/debug.log"
echo "" >> "$LOG_DIR/debug.log"

# Return output
echo "$OUTPUT"
exit $EXIT_CODE