# Advanced Hooks Configuration

> Hooks I should be aware of and how they help

---

## Currently Active Hooks

From `.claude/settings.json`:
```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": "Edit", "command": "black \"$FILEPATH\" --quiet"},
      {"matcher": "Write", "command": "black \"$FILEPATH\" --quiet"}
    ],
    "PreCommit": [
      {"command": "python tree_gen.py"}
    ]
  }
}
```

---

## Hooks We Should Add

### 1. PreCompact Hook (Memory Persistence)
**Purpose:** Save important state before context compaction

```json
{
  "PreCompact": [
    {
      "command": "echo 'CONTEXT COMPACTING - Saving state...' && date >> .claude/memory/sessions/compact-log.txt"
    }
  ]
}
```

**What I should do when PreCompact fires:**
1. Mentally note what we're working on
2. Ensure critical context is in memory files
3. The user will see "CONTEXT COMPACTING" message

### 2. Stop Hook (Session End Learning)
**Purpose:** Persist learnings when session ends

```json
{
  "Stop": [
    {
      "command": "echo 'Session ended' >> .claude/memory/sessions/session-log.txt"
    }
  ]
}
```

**What I should do at session end:**
1. Review what we learned
2. Update wins.md/fails.md if applicable
3. Create diary entry if significant work done

### 3. PostToolUse: TypeScript/Python Checks
**Purpose:** Catch errors immediately after edits

```json
{
  "PostToolUse": [
    {"matcher": "Edit && .py", "command": "python -m py_compile \"$FILEPATH\" 2>&1 || true"},
    {"matcher": "Edit && .ts", "command": "npx tsc --noEmit \"$FILEPATH\" 2>&1 || true"}
  ]
}
```

### 4. PreToolUse: Dangerous Command Warning
**Purpose:** Warn before risky operations

```json
{
  "PreToolUse": [
    {
      "matcher": "Bash && (rm -rf|git push --force|git reset --hard)",
      "command": "echo '⚠️ DANGEROUS COMMAND DETECTED' >&2"
    }
  ]
}
```

---

## Hook Types Reference

| Hook | When It Fires | Use For |
|------|---------------|---------|
| PreToolUse | Before tool executes | Validation, warnings |
| PostToolUse | After tool completes | Formatting, type checks |
| UserPromptSubmit | When user sends message | (Avoid - adds latency) |
| Stop | When I finish responding | Session-end tasks |
| PreCompact | Before context compaction | Emergency state save |
| Notification | Permission requests | Custom prompts |

---

## Best Practices

1. **Use Stop, not UserPromptSubmit** for learning
   - UserPromptSubmit runs on EVERY message (slow)
   - Stop runs once at session end (efficient)

2. **Keep hooks fast**
   - Slow hooks = slow responses
   - Use `|| true` to prevent blocking on errors

3. **Log to files, not stdout**
   - Hooks output can clutter the terminal
   - Write to log files instead

4. **Match specifically**
   - Don't run expensive checks on every file
   - Use matchers to target specific file types

---

## Recommended Full Config

```json
{
  "hooks": {
    "PostToolUse": [
      {"matcher": "Edit && .py", "command": "black \"$FILEPATH\" --quiet 2>/dev/null || true"},
      {"matcher": "Write && .py", "command": "black \"$FILEPATH\" --quiet 2>/dev/null || true"},
      {"matcher": "Edit && .py", "command": "python -m py_compile \"$FILEPATH\" 2>&1 || true"}
    ],
    "PreCommit": [
      {"command": "python tree_gen.py"}
    ],
    "PreCompact": [
      {"command": "echo \"[$(date)] Context compacting\" >> .claude/memory/sessions/compact-log.txt"}
    ],
    "Stop": [
      {"command": "echo \"[$(date)] Session ended\" >> .claude/memory/sessions/session-log.txt"}
    ]
  }
}
```

---

*These hooks automate quality checks and memory persistence*
