# 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`:

```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)

```json
{
  "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