# Claude Code Hooks Setup

These hooks must be configured manually in `~/.claude/settings.json` on each machine.
They cannot be committed to a repo (global user settings only).

---

## Required Hooks

### 1. Docker Auto-Rebuild (PostToolUse)

**Trigger:** After any `Write` or `Edit` tool call
**Behavior:** If a `docker-compose.yml` or `docker-compose.yaml` exists in the project root, automatically rebuilds and restarts containers. Detects v2 (`docker compose`) and falls back to v1 (`docker-compose`).

### 2. README Auto-Update (Stop)

**Trigger:** When Claude finishes responding (once per task, not per edit)
**Behavior:** An AI agent checks if `README.md` exists in the project. If it does, reviews changes made during the session and updates the README with any new/changed functionality, config, endpoints, env vars, or setup steps. Only updates if there's genuinely new information.

---

### 3. Auto-Sync Preferences (UserPromptSubmit)

**Trigger:** Before each user message
**Behavior:** Runs `git pull` in the local clone of this preferences repo. Because `CLAUDE.md` and `preferences/` are symlinked into `~/.claude/`, the pull immediately updates what Claude sees without any manual steps. Silently skips if already up to date or unreachable.

Requires the one-time symlink + clone setup described in this repo's `README.md`.

---

## Settings JSON

Add this to `~/.claude/settings.json` (merge with any existing content). Commands differ by platform — use the block that matches your machine.

#### Linux

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "if [ -f \"docker-compose.yml\" ] || [ -f \"docker-compose.yaml\" ]; then if docker compose version >/dev/null 2>&1; then docker compose up --build -d; elif command -v docker-compose >/dev/null 2>&1; then docker-compose up --build -d; fi; fi 2>/dev/null || true",
            "async": true,
            "statusMessage": "Rebuilding Docker containers..."
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Check if a README.md file exists in the current project directory. If it does, review what changes were made during this session and update README.md to reflect any new or changed functionality, configuration, API endpoints, environment variables, or setup steps. Only make updates if there is genuinely new or changed information that belongs in a README. Preserve the existing format and style. If nothing meaningful changed, leave the README as-is.",
            "statusMessage": "Checking README for updates...",
            "timeout": 120
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git -C \"$HOME/AI\" pull --quiet --ff-only 2>/dev/null; true",
            "async": true,
            "statusMessage": "Syncing preferences..."
          }
        ]
      }
    ]
  }
}
```

#### Windows

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Check if a README.md file exists in the current project directory. If it does, review what changes were made during this session and update README.md to reflect any new or changed functionality, configuration, API endpoints, environment variables, or setup steps. Only make updates if there is genuinely new or changed information that belongs in a README. Preserve the existing format and style. If nothing meaningful changed, leave the README as-is.",
            "statusMessage": "Checking README for updates...",
            "timeout": 120
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "powershell -NonInteractive -Command \"git -C C:\\AI pull --quiet --ff-only 2>$null\"",
            "async": true,
            "statusMessage": "Syncing preferences..."
          }
        ]
      }
    ]
  }
}
```

---

## Setup on a New Machine

When setting up Claude Code on a new machine, ask the AI:

> "Read preferences/hooks-setup.md and configure my ~/.claude/settings.json with the required hooks."