creating-hooks

STARTER_CHARACTER = 🪝

Setup

First, update the reference docs to get the latest from Anthropic:

python ~/.claude/skills/creating-hooks/scripts/update-docs.py

What Hooks Are

Shell commands that execute at lifecycle points in Claude Code. Unlike prompts, hooks are deterministic—they always run when triggered.

Configuration

Hooks live in settings files:

• ~/.claude/settings.json - User settings (all projects)
• .claude/settings.json - Project settings (shared via git)
• .claude/settings.local.json - Local project settings (not committed)

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

Matcher: Pattern to match tool names (case-sensitive)

• Exact match: Write
• Regex: Edit|Write
• All tools: * or omit

Environment variables:

• $CLAUDE_PROJECT_DIR - Absolute path to project root
• $CLAUDE_ENV_FILE - File path for persisting env vars (SessionStart only)

Hook Events

Tool events (matcher applies):

• PreToolUse - Before tool executes
• PostToolUse - After tool completes
• PermissionRequest - Permission dialog shown

Session events:

• SessionStart - Session begins/resumes (matcher: startup/resume/clear/compact)
• SessionEnd - Session ends
• PreCompact - Before compaction (matcher: manual/auto)

Other events:

• UserPromptSubmit - User submits prompt
• Stop - Agent finishes
• SubagentStop - Subagent finishes
• Notification - Alerts sent (matcher: notification type)

Exit Codes

• 0: Success. stdout shown in verbose mode. For UserPromptSubmit/SessionStart, stdout added to context.
• 2: Block. stderr fed to Claude as error message. Blocks the action.
• Other: Non-blocking error. stderr shown to user.

JSON Output

For advanced control, return JSON to stdout with exit code 0:

{
  "continue": false,
  "stopReason": "Message shown when stopping"
}