creating-hooks

Creating Hooks

Guides creation of Claude Code hooks for automation and workflow customization.

Quick Start

1. Choose hook event (when should it trigger?)
2. Configure in settings.json
3. Create hook script
4. Test the hook

Workflow: Create New Hook

Progress:
- [ ] Select hook event
- [ ] Add to settings.json
- [ ] Create hook script
- [ ] Test and validate

Step 1: Select Hook Event

| Event | When It Triggers | Common Use | |-------|------------------|------------| | PreToolUse | Before tool runs | Block/modify tools | | PostToolUse | After tool succeeds | Validate, log, feedback | | UserPromptSubmit | User sends message | Inject context, validate | | SessionStart | Session begins | Load context, init state | | SessionEnd | Session ends | Cleanup, save state | | Stop | Agent finishes | Decide if should continue |

Full event reference: [reference.md](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/](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

| Code | Meaning | Behavior | |------|---------|----------| | 0 | Success | Continue normally | | 2 | Block | Stop action, show error | | Other | Non-blocking error | Log only (verbose mode) |

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](reference.md) for complete event details and more examples.