hooks-builder

# Hooks Builder

A comprehensive guide for creating Claude Code hooks — event-driven automation that monitors and controls Claude's actions.

## Quick Reference

### The 10 Hook Events

| Event | When It Fires | Can Block? | Supports Matchers? |
|-------|--------------|------------|-------------------|
| **PreToolUse** | Before tool executes | YES | YES (tool names) |
| **PermissionRequest** | Permission dialog shown | YES | YES (tool names) |
| **PostToolUse** | After tool succeeds | No | YES (tool names) |
| **Notification** | Claude sends notification | No | YES |
| **UserPromptSubmit** | User submits prompt | YES | No |
| **Stop** | Claude finishes responding | Can force continue | No |
| **SubagentStop** | Subagent finishes | Can force continue | No |
| **PreCompact** | Before context compaction | No | YES (manual/auto) |
| **SessionStart** | Session begins | No | YES (startup/resume/clear/compact) |
| **SessionEnd** | Session ends | No | No |

### Exit Code Semantics

| Exit Code | Meaning | Effect |
|-----------|---------|--------|
| **0** | Success | stdout parsed as JSON for control |
| **2** | Blocking error | **VETO** — stderr shown to Claude |
| **Other** | Non-blocking error | stderr logged in debug mode |

### Configuration Locations

```
~/.claude/settings.json          → Personal hooks (all projects)
.claude/settings.json            → Project hooks (team, committed)
.claude/settings.local.json      → Local overrides (not committed)
```

### Essential Environment Variables

| Variable | Description |
|----------|-------------|
| `$CLAUDE_PROJECT_DIR` | Project root directory |
| `$CLAUDE_CODE_REMOTE` | Remote/local indicator |
| `$CLAUDE_ENV_FILE` | Environment persistence path (SessionStart) |
| `$CLAUDE_PLUGIN_ROOT` | Plugin directory (plugin hooks) |

### Key Commands

```bash
/hooks              # View active hooks
claude --debug      # Enable debug logging
chmod +x script.sh  # Make script executable
```

---

## 6-Phase Workflow

### Phase 1: Re