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.

Settings JSON

Add this to ~/.claude/settings.json (merge with any existing content):

{
  "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
          }
        ]
      }
    ]
  }
}

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."

2.4 KiB Raw Blame History