hooks

# Claude Code Hooks

## Overview

Claude Code hooks are automated scripts that execute at specific lifecycle events, enabling validation, transformation, and control over tool execution and session management.

## Configuration Structure

Hooks are configured in settings files (`~/.claude/settings.json`, `.claude/settings.json`, or `.claude/settings.local.json`) using this pattern:

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

**Key features:**
- Matchers use case-sensitive patterns (regex supported)
- Use `*` or empty string to match all tools
- Optional timeout configuration (default: 60 seconds)
- `$CLAUDE_PROJECT_DIR` environment variable available for project-relative paths

## Hook Events

### PreToolUse & PostToolUse
Executes before/after tool operations. Supports matchers for:
- Task, Bash, Glob, Grep, Read, Edit, Write, WebFetch, WebSearch

### UserPromptSubmit
Runs when the user submits a prompt, before Claude processes it, enabling context injection and prompt validation.

### Notification
Triggers when Claude requests permissions or waits for input.

### Stop & SubagentStop
Executes when agents complete responses.

### SessionStart
Useful for loading in development context like existing issues or recent changes to your codebase, installing dependencies, or setting up environment variables.

**Environment persistence:**
Use `CLAUDE_ENV_FILE` to persist variables across bash commands:
```bash
echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
```

### SessionEnd
Runs during session cleanup with `reason` field (clear, logout, prompt_input_exit, other).

### PreCompact
Executes before context compaction with matchers: `manual` or `auto`.

## Hook Input/Output

**Input delivered via stdin as JSON containing:**
- session_id, transcript_path,