Creating Hooks

Full event reference: reference.md

Step 2: Configure settings.json

Location priority (highest wins):

1. .claude/settings.local.json (local, not committed)
2. .claude/settings.json (project)
3. ~/.claude/settings.json (user)

Basic structure:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/my-hook.sh\""
          }
        ]
      }
    ]
  }
}

Step 3: Create Hook Script

Use templates from templates/ directory.

Key requirements:

• Read JSON from stdin
• Use exit codes for control (0=success, 2=block)
• Output JSON for decisions

Step 4: Test

Run hook manually with test input:

echo '{"tool_name":"Write"}' | bash .claude/hooks/my-hook.sh

Hook Configuration

Matcher Patterns

"matcher": "Write"           // Exact match
"matcher": "Edit|Write"      // Multiple tools
"matcher": "mcp__.*"         // MCP tools (regex)
"matcher": "*"               // All tools

Matchers apply to: PreToolUse, PostToolUse, PermissionRequest

Timeout

{
  "type": "command",
  "command": "...",
  "timeout": 120
}

Default: 60 seconds. Max recommended: 300 seconds.

Exit Codes

JSON Output

Return JSON to stdout for decisions:

{
  "decision": "block",
  "reason": "Why blocked",
  "additionalContext": "Info for Claude"
}

Decision values by event:

• PreToolUse: allow, deny, ask
• PostToolUse: block (with reason)
• UserPromptSubmit: block (with reason)
• Stop: block (requires reason)

Security Best Practices

1. Quote all variables: "$VAR" not $VAR
2. Use absolute paths: "$CLAUDE_PROJECT_DIR/..."
3. Validate inputs: Check before processing
4. Block path traversal: Reject paths with ..
5. Set timeouts: Prevent runaway scripts

Environment Variables

Available in all hooks:

• CLAUDE_PROJECT_DIR - Project root path
• CLAUDE_CODE_REMOTE - "true" if web environment

SessionStart only:

• CLAUDE_ENV_FILE - Path to persist env vars

Common Patterns

Inject Context on Session Start

#!/bin/bash
# Output context for Claude
echo '{"additionalContext": "Project uses TypeScript"}'
exit 0

Block Dangerous File Edits

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
if [[ "$FILE" == *".env"* ]]; then
  echo "Blocking edit to sensitive file" >&2
  exit 2
fi
exit 0

Log All Tool Usage

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
echo "$(date -Iseconds) $TOOL" >> "$CLAUDE_PROJECT_DIR/.claude/tool.log"
exit 0

See reference.md for complete event details and more examples.