Hook Lab

HookLab

A web dashboard for watching Claude Code hook events in real time.



Quickstart

services:
  app:
    image: ghcr.io/felipeelias/hook-lab:latest
    ports:
      - "4000:4000"
    volumes:
      - hook_lab_data:/app/data
    environment:
      SECRET_KEY_BASE: ${SECRET_KEY_BASE}
      DATABASE_PATH: /app/data/hook_lab.db
      PHX_HOST: localhost

volumes:
  hook_lab_data:

export SECRET_KEY_BASE=$(openssl rand -base64 64)
docker compose up -d

Open http://localhost:4000.

Hook configuration

This repo includes a [`docs/claude-settings.example.json`](docs/claude-settings.example.json) that sends every hook event to HookLab over HTTP. Each hook has a 1-second timeout. If HookLab isn't running, Claude Code moves on.

Copy the `hooks` block from that file into `~/.claude/settings.json` or your project's `.claude/settings.json`. Here's a stripped-down version with just two events if you want to start small:

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:4000/api/hooks",
            "timeout": 1
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:4000/api/hooks",
            "timeout": 1
          }
        ]
      }
    ]
  }
}

Hook settings are read at session start, so open a new Claude Code session after changing them.

Custom URL

If HookLab is running on a different host or port, replace `http://localhost:4000/api/hooks` in each hook entry with your URL. HTTP hooks don't support environment variable interpolation in the `url` field, so the URL must be edited directly in the settings file.

Development

mix setup
mix phx.server
# http://localhost:4000

mix ci

docker compose build