---

name: adding-hooks description: Add and configure Claude Code hooks for event-driven automation. Use when setting up hooks, creating hook scripts, or automating tool-related workflows.

Claude Code Hooks Configuration

Quick Start

First, ask the user where to add hooks:

• ~/.claude/settings.json - User-scoped (personal, all projects)
• .claude/settings.json - Project-scoped (shared via git)
• .claude/settings.local.json - Local project (not committed)
• Plugin hooks/hooks.json - Plugin-bundled hooks

Basic Structure

Copy{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Hook Events

See events.md for detailed event documentation.

Matchers

For PreToolUse, PostToolUse, PermissionRequest:

• Exact match: "Write" - matches Write tool only
• Regex: "Edit|Write" - matches Edit or Write
• All tools: "*" or "" or omit matcher
• MCP tools: "mcp__server__tool" pattern

Case-sensitive: Write ≠ write

Hook Types

Command Hooks

Copy{
  "type": "command",
  "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/check.sh",
  "timeout": 30
}

Prompt Hooks (LLM evaluation)

Copy{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks complete.",
  "timeout": 30
}

Supported for: Stop, SubagentStop, UserPromptSubmit, PreToolUse, PermissionRequest

Exit Codes

Common Patterns

Auto-format on Write/Edit

Copy{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/format.sh"
          }
        ]
      }
    ]
  }
}

Validate Bash Commands

Copy{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/validate-bash.sh"
          }
        ]
      }
    ]
  }
}

Inject Context on Prompt

Copy{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Current time: $(date)\""
          }
        ]
      }
    ]
  }
}

Protect Files

Copy{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Hook Script Template

Copy#!/usr/bin/env bash
set -euo pipefail

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

# Parse fields with jq
tool_name=$(echo "$input" | jq -r '.tool_name // empty')
tool_input=$(echo "$input" | jq -r '.tool_input // empty')

# Validation logic here

# Exit 0: success, Exit 2: block with stderr message
exit 0

See scripts.md for script examples.

JSON Output (Advanced)

For structured control, output JSON to stdout (exit code 0):

Copy{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Auto-approved"
  }
}

See json-output.md for complete schema.

Environment Variables

Security Best Practices

1. Quote variables: "$VAR" not $VAR
2. Validate input: Don't trust stdin blindly
3. Block path traversal: Check for .. in paths
4. Use absolute paths: Full script paths
5. Skip sensitive files: Avoid .env, .git/, keys

Debugging

Copy# Check registered hooks
/hooks

# Debug mode for execution details
claude --debug

Common issues:

• Unescaped quotes in JSON: Use \"
• Wrong matcher case: Write not write
• Missing executable permission: chmod +x script.sh

Resources

• events.md - Detailed event documentation
• scripts.md - Hook script examples
• json-output.md - JSON output schema