Hooks System Mastery

Claude Code’s hooks system (introduced July 2025) enables powerful event-driven automation. By executing custom commands at specific points in Claude’s workflow, you can enforce standards, automate quality checks, and create sophisticated development workflows - all without manual intervention.

Understanding Hooks

Hooks are shell commands that execute automatically when specific events occur in Claude Code. Think of them as lifecycle callbacks that let you inject custom behavior into Claude’s operations.

Hook Events

PreToolUse

Before tool execution - Validate, block, or modify tool calls before they run. Perfect for security checks and input validation.

PostToolUse

After tool completion - React to successful operations. Ideal for formatting, notifications, and follow-up actions.

UserPromptSubmit

When user submits prompt - Process or enhance prompts before Claude sees them. Add context or validate requests.

Stop

When Claude finishes - Cleanup, reporting, or triggering next steps after Claude completes its response.

Additional events:

• Notification - When Claude needs permission or is idle
• SubagentStop - When subagent tasks complete
• PreCompact - Before conversation compression

Quick Start: Your First Hook

1. Open hooks configuration

   /hooks
   # Select: PreToolUse

2. Add a matcher for Edit tool

   Matcher: Edit

3. Add formatting hook

   prettier --write "$CLAUDE_FILE_PATHS" 2>/dev/null || true

4. Save to project settings Choose .claude/settings.json for team sharing

Now every file Claude edits will be automatically formatted!

Hook Configuration

Settings File Structure

Project Settings

// .claude/settings.json (shared with team)
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATHS\"",
            "timeout": 5000
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/security-check.sh"
          }
        ]
      }
    ]
  }
}

User Settings

// ~/.claude/settings.json (personal)
{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Enterprise Policy

/etc/claude-code/managed-settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/security/audit-command.sh"
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Matchers determine which tools trigger your hooks:

Pattern	Description	Example
Edit	Exact match	Only Edit tool
Edit|Write	Multiple tools	Edit OR Write
Notebook.*	Regex pattern	NotebookEdit, NotebookRead
"" or omitted	All tools	Every tool call
mcp__.*__.*	MCP tools	All MCP server tools

Hook Input and Output

Input Data Structure

Hooks receive JSON via stdin:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/conversation.jsonl",
  "cwd": "/current/working/directory",
  "hook_event_name": "PreToolUse",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "/src/index.js",
    "content": "// File content here"
  }
}

Output Control

Hooks communicate through exit codes and output:

Simple: Exit Codes

Exit Code	Effect	Use Case
0	Success, continue	Normal flow
2	Block with feedback	Validation failed
Other	Non-blocking error	Warning only

security-check.sh

#!/bin/bash
if [[ "$1" =~ rm\ -rf ]]; then
  echo "Dangerous command blocked" >&2
  exit 2
fi
exit 0

Advanced: JSON Output

advanced-hook.sh

#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')

if [[ "$TOOL_NAME" == "Edit" ]]; then
  cat <<EOF
{
  "decision": "approve",
  "reason": "Edit approved after validation",
  "suppressOutput": true
}
EOF
else
  cat <<EOF
{
  "decision": "block",
  "reason": "Only Edit tool allowed in this context"
}
EOF
fi

Practical Hook Patterns

Code Quality Automation

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'if [[ \"$CLAUDE_FILE_PATHS\" =~ \\.(js|ts|jsx|tsx)$ ]]; then prettier --write \"$CLAUDE_FILE_PATHS\" && eslint --fix \"$CLAUDE_FILE_PATHS\"; fi'"
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'if [[ \"$CLAUDE_FILE_PATHS\" =~ \\.(py)$ ]]; then black \"$CLAUDE_FILE_PATHS\" && ruff check --fix \"$CLAUDE_FILE_PATHS\"; fi'"
          }
        ]
      }
    ]
  }
}

Security and Compliance

pre-edit-security.sh

#!/bin/bash
set -e

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

# Prevent editing sensitive files
FORBIDDEN_PATTERNS=(
  "*.env"
  "*.key"
  "*.pem"
  "**/secrets/*"
  "**/config/production.json"
)

for pattern in "${FORBIDDEN_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == $pattern ]]; then
    echo "Security policy prevents editing $FILE_PATH" >&2
    exit 2
  fi
done

# Check for secrets in content
CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // empty')
if echo "$CONTENT" | grep -qE '(api_key|password|secret).*=.*["\x27]'; then
  echo "Potential secret detected in code" >&2
  exit 2
fi

exit 0

Development Workflow Automation

• Folder.claude/

  • Folderhooks/

    • post-edit-typescript.sh
    • pre-bash-validate.sh
    • notification-handler.sh
    • stop-cleanup.sh

post-edit-typescript.sh

#!/bin/bash
# Comprehensive TypeScript workflow

set -e
INPUT=$(cat)
FILES=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for FILE in $FILES; do
  if [[ "$FILE" =~ \.(ts|tsx)$ ]]; then
    # Format
    prettier --write "$FILE"

    # Type check
    npx tsc --noEmit --skipLibCheck "$FILE" || {
      echo "TypeScript errors in $FILE - please review"
      # Don't fail, just warn
    }

    # Update tests if needed
    TEST_FILE="${FILE%.ts}.test.ts"
    if [[ -f "$TEST_FILE" ]]; then
      echo "Remember to update tests: $TEST_FILE"
    fi

    # Generate/update documentation
    npx typedoc --emit none --validation "$FILE" 2>/dev/null || true
  fi
done

Smart Notifications

notification-handler.sh

#!/bin/bash
# Platform-aware notifications

INPUT=$(cat)
MESSAGE=$(echo "$INPUT" | jq -r '.message // "Claude needs attention"')

# macOS
if command -v osascript &> /dev/null; then
  osascript -e "display notification \"$MESSAGE\" with title \"Claude Code\" sound name \"Glass\""

# Linux with notify-send
elif command -v notify-send &> /dev/null; then
  notify-send "Claude Code" "$MESSAGE" --urgency=normal --icon=dialog-information

# Windows WSL
elif command -v powershell.exe &> /dev/null; then
  powershell.exe -Command "
    Add-Type -AssemblyName System.Windows.Forms
    \$notification = New-Object System.Windows.Forms.NotifyIcon
    \$notification.Icon = [System.Drawing.SystemIcons]::Information
    \$notification.BalloonTipIcon = 'Info'
    \$notification.BalloonTipTitle = 'Claude Code'
    \$notification.BalloonTipText = '$MESSAGE'
    \$notification.Visible = \$true
    \$notification.ShowBalloonTip(5000)
  "
fi

# Also log to file
echo "[$(date)] $MESSAGE" >> ~/.claude/notifications.log

Advanced Hook Techniques

Context Enhancement

enhance-prompt.sh

#!/bin/bash
# Add context to user prompts

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

# Add git context
GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "no-git")
GIT_STATUS=$(git status --porcelain | wc -l)

# Add system context
NODE_VERSION=$(node -v 2>/dev/null || echo "no-node")

# Output enhanced prompt
cat <<EOF
{
  "prompt": "$PROMPT\n\nContext: Branch=$GIT_BRANCH, Uncommitted=$GIT_STATUS files, Node=$NODE_VERSION",
  "continue": true
}
EOF

Conditional Execution

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "sh -c 'if [ \"$CI\" = \"true\" ]; then echo \"Skipping format in CI\"; else prettier --write \"$CLAUDE_FILE_PATHS\"; fi'"
          }
        ]
      }
    ]
  }
}

MCP Tool Hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__database__.*",
        "hooks": [
          {
            "type": "command",
            "command": "/opt/audit/log-database-access.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "mcp__github__create_pr",
        "hooks": [
          {
            "type": "command",
            "command": "slack-cli send --channel #dev-prs --text 'New PR created by Claude'"
          }
        ]
      }
    ]
  }
}

Hook Development Best Practices

Error Handling

Uwaga

Always handle errors gracefully in hooks. A crashing hook can interrupt Claude’s workflow.

#!/bin/bash
# Robust hook template

set -euo pipefail
trap 'echo "Hook failed: $?" >&2' ERR

# Safe JSON parsing
INPUT=$(cat)
if ! echo "$INPUT" | jq empty 2>/dev/null; then
  echo "Invalid JSON input" >&2
  exit 1
fi

# Main logic with fallbacks
{
  # Your hook logic here
  :
} || {
  echo "Non-critical error, continuing" >&2
  exit 0  # Don't block Claude
}

Performance Optimization

• Set timeouts to prevent hanging:

  {
    "type": "command",
    "command": "your-command",
    "timeout": 5000  // 5 seconds
  }

• Run async when possible:

  # Don't block Claude for non-critical tasks
  {
    sleep 2
    curl -X POST https://webhook.site/...
  } &

• Cache expensive operations:

  CACHE_FILE="/tmp/claude-hook-cache-$(date +%Y%m%d)"
  if [[ ! -f "$CACHE_FILE" ]]; then
    expensive_operation > "$CACHE_FILE"
  fi
  cat "$CACHE_FILE"

Security Considerations

Security Warning

Hooks run with your user permissions. Never trust untrusted input and always validate data.

# Secure hook practices

# 1. Validate and sanitize input
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path' | sed 's/[^a-zA-Z0-9./_-]//g')

# 2. Use absolute paths
SAFE_DIR="/home/user/project"
if [[ ! "$FILE_PATH" =~ ^"$SAFE_DIR" ]]; then
  echo "Access denied: outside project directory" >&2
  exit 2
fi

# 3. Quote all variables
command "$FILE_PATH" # Bad
command "$FILE_PATH" # Good

# 4. Avoid eval and injection
eval "$USER_INPUT" # Never do this

Debugging Hooks

Enable Debug Mode

# Launch with debug output
claude --debug

# Check hook execution
[DEBUG] Executing hooks for PostToolUse:Edit
[DEBUG] Hook command completed with status 0

Test Hooks Independently

# Test your hook with sample input
echo '{
  "hook_event_name": "PreToolUse",
  "tool_name": "Edit",
  "tool_input": {
    "file_path": "test.js"
  }
}' | ./my-hook.sh

Common Issues

Issue	Solution
Hook not triggering	Check matcher pattern and JSON syntax
Permission denied	Make script executable: chmod +x hook.sh
Command not found	Use absolute paths or check PATH
Timeout errors	Increase timeout or optimize script

Real-World Examples

Complete Development Workflow

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-edit-checks.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/format-and-lint.sh"
          },
          {
            "type": "command",
            "command": ".claude/hooks/run-affected-tests.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/generate-commit-message.sh"
          }
        ]
      }
    ]
  }
}

Team Collaboration Hooks

Share hooks with your team:

# In your repo
git add .claude/hooks/ .claude/settings.json
git commit -m "Add Claude Code automation hooks"
git push

# Team members get automation automatically!

Next Steps

Master these advanced hook patterns:

1. Combine with Custom Commands for powerful macros
2. Integrate with Memory Management for context-aware hooks
3. Configure Enterprise Setup for organization-wide automation

Wskazówka

The most powerful automations combine hooks, custom commands, and smart memory management. Start simple, then build sophistication as you identify patterns in your workflow.