claude-code/hooks/README.md

Hooks

Event handlers that run automatically during Claude Code sessions.

Active Hooks

Event	Script	Purpose
SessionStart	scripts/session-start.sh	Load context, check for pending items

Hook Events

Event	When It Fires
SessionStart	When Claude Code session begins
SessionEnd	When session ends
PreToolUse	Before a tool is used
PostToolUse	After a tool is used
UserPromptSubmit	When user submits a prompt
PreCompact	Before context compaction
Notification	When notification is sent

Configuration

Hooks are defined in hooks.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/scripts/session-start.sh"
          }
        ]
      }
    ]
  }
}

Adding Hooks

1. Create script in scripts/
2. Make executable: chmod +x scripts/your-hook.sh
3. Add to hooks.json
4. Restart Claude Code

Script Output

• Stdout is injected into session as context
• Use format: HookName:Callback hook success: Success
• Additional context: HookName hook additional context: <message>

Matchers (for Tool Hooks)

{
  "matcher": "Write|Edit",
  "hooks": [...]
}

Matches tool names with regex pattern.

Tips

• Keep hooks fast (<1s) to avoid delays
• Use set -euo pipefail for safety
• Output useful context, not noise
• Test hooks manually before adding