Overview

Hooks allow you to intercept Claude Code's operations at specific points in the workflow. They can approve, deny, or modify tool invocations, add context to responses, and automate permission decisions.

Configuration

Settings File Locations

Hooks are configured in your Claude Code settings files, checked in order of precedence:

Basic Structure

{
  "hooks": [
    {
      "matcher": "Read",
      "event": "PreToolUse",
      "type": "command",
      "command": "python ~/.claude/hooks/auto_approve_reads.py"
    }
  ]
}

Hook Configuration Fields

Hook Types

{
  "matcher": "Bash",
  "event": "PreToolUse",
  "type": "command",
  "command": "python ~/.claude/hooks/validate_bash.py"
}

{
  "matcher": "Write",
  "event": "PreToolUse",
  "type": "prompt",
  "prompt": "Review this file write operation:\n{{toolCall}}\n\nApprove only if the change seems safe and follows project conventions."
}

Hook Events

Hooks can be triggered at different points in Claude Code's lifecycle:

Hook Input/Output

Input Format (stdin)

Hooks receive JSON input via stdin with context about the event:

{
  "event": "PreToolUse",
  "toolName": "Write",
  "toolCall": {
    "file_path": "/path/to/file.txt",
    "content": "Hello, world!"
  },
  "context": {
    "projectDir": "/Users/user/project",
    "conversationId": "abc123"
  }
}

Exit Codes

Output Format (stdout)

Hooks return JSON to stdout to communicate decisions:

{
  "decision": "approve",
  "reason": "File path is safe and within project directory",
  "updatedInput": {
    "file_path": "/validated/path/file.txt",
    "content": "Hello, world!"
  },
  "additionalContext": "This file was auto-approved by security hook",
  "hookSpecificOutput": {
    "validationPassed": true,
    "checks": ["path", "content", "permissions"]
  }
}

Response Fields

Practical Examples

Bash Command Validation

Prevent dangerous commands from being executed:

{
  "hooks": [
    {
      "matcher": "Bash",
      "event": "PreToolUse",
      "type": "command",
      "command": "python ~/.claude/hooks/validate_bash.py"
    }
  ]
}

#!/usr/bin/env python3
import sys
import json

# Read hook input
hook_input = json.loads(sys.stdin.read())
command = hook_input.get("toolCall", {}).get("command", "")

# Dangerous patterns
dangerous_patterns = [
    "rm -rf /",
    ":(){ :|:& };:",  # Fork bomb
    "> /dev/sda",
    "mkfs",
    "dd if=/dev/random"
]

# Check for dangerous commands
for pattern in dangerous_patterns:
    if pattern in command:
        print(json.dumps({
            "decision": "deny",
            "reason": f"Blocked dangerous command pattern: {pattern}"
        }))
        sys.exit(2)

# Approve safe commands
print(json.dumps({
    "decision": "approve",
    "reason": "Command passed safety validation"
}))
sys.exit(0)

Auto-Approve Read Operations

Automatically approve safe read operations to reduce friction:

{
  "hooks": [
    {
      "matcher": "Read",
      "event": "PreToolUse",
      "type": "command",
      "command": "python ~/.claude/hooks/auto_approve_reads.py"
    }
  ]
}

#!/usr/bin/env python3
import sys
import json
import os

hook_input = json.loads(sys.stdin.read())
file_path = hook_input.get("toolCall", {}).get("file_path", "")
project_dir = hook_input.get("context", {}).get("projectDir", "")

# Auto-approve if within project directory
if file_path.startswith(project_dir):
    # Check file size to avoid reading huge files
    if os.path.exists(file_path):
        file_size = os.path.getsize(file_path)
        if file_size > 10 * 1024 * 1024:  # 10MB limit
            print(json.dumps({
                "decision": "deny",
                "reason": f"File too large: {file_size / 1024 / 1024:.2f}MB"
            }))
            sys.exit(2)

    print(json.dumps({
        "decision": "approve",
        "reason": "Auto-approved: file within project directory"
    }))
    sys.exit(0)

# Deny reads outside project
print(json.dumps({
    "decision": "deny",
    "reason": "File is outside project directory"
}))
sys.exit(2)

Intelligent Stop Hook

Extract action items when conversation ends:

{
  "hooks": [
    {
      "event": "Stop",
      "type": "prompt",
      "prompt": "Review this conversation and extract any action items, TODOs, or follow-up tasks:\n\n{{conversation}}\n\nFormat as a markdown checklist."
    }
  ]
}

Context Enhancement

Add architectural context after reading files:

{
  "hooks": [
    {
      "matcher": "Read",
      "event": "PostToolUse",
      "type": "command",
      "command": "python ~/.claude/hooks/add_architecture_context.py"
    }
  ]
}

#!/usr/bin/env python3
import sys
import json
import os

hook_input = json.loads(sys.stdin.read())
file_path = hook_input.get("toolCall", {}).get("file_path", "")

# Add context based on file type
context = ""
if file_path.endswith(".py"):
    context = "Note: This project uses FastAPI framework with async/await patterns."
elif file_path.endswith((".tsx", ".jsx")):
    context = "Note: This is a React component using TypeScript and hooks."
elif "database" in file_path.lower():
    context = "Note: This project uses PostgreSQL with SQLAlchemy ORM."

print(json.dumps({
    "decision": "approve",
    "additionalContext": context
}))
sys.exit(0)

Environment Variables

Hooks have access to special environment variables:

#!/bin/bash
echo "Project: $CLAUDE_PROJECT_DIR"

if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
  echo "Running in remote environment"
fi

import os
env_file = os.environ.get("CLAUDE_ENV_FILE")
if env_file:
    # Load environment variables from file
    pass

MCP Tools Support

Hooks can intercept MCP (Model Context Protocol) tools using the naming pattern:

mcp__<server-name>__<tool-name>

Example: MCP Tool Hook

{
  "hooks": [
    {
      "matcher": "mcp__filesystem__read_file",
      "event": "PreToolUse",
      "type": "command",
      "command": "python ~/.claude/hooks/validate_mcp_read.py"
    }
  ]
}

Match All MCP Tools

Use regex to match all tools from a specific MCP server:

{
  "hooks": [
    {
      "matcher": "mcp__github__.*",
      "event": "PreToolUse",
      "type": "command",
      "command": "python ~/.claude/hooks/audit_github_access.py"
    }
  ]
}

Best Practices

Security Considerations

Security Checklist

Example: Path Validation

#!/usr/bin/env python3
import sys
import json
import os
from pathlib import Path

hook_input = json.loads(sys.stdin.read())
file_path = hook_input.get("toolCall", {}).get("file_path", "")
project_dir = hook_input.get("context", {}).get("projectDir", "")

# Resolve to absolute path and check if within project
try:
    abs_path = Path(file_path).resolve()
    abs_project = Path(project_dir).resolve()

    # Check if path is within project (prevents directory traversal)
    if not str(abs_path).startswith(str(abs_project)):
        print(json.dumps({
            "decision": "deny",
            "reason": "Path is outside project directory"
        }))
        sys.exit(2)

    # Additional checks for sensitive files
    sensitive_patterns = [".env", "secrets", "credentials", ".ssh", ".aws"]
    if any(pattern in str(abs_path).lower() for pattern in sensitive_patterns):
        print(json.dumps({
            "decision": "deny",
            "reason": "Access to sensitive files requires manual approval"
        }))
        sys.exit(2)

    print(json.dumps({"decision": "approve"}))
    sys.exit(0)

except Exception as e:
    print(json.dumps({
        "decision": "deny",
        "reason": f"Path validation error: {str(e)}"
    }))
    sys.exit(2)

Related