Vigil

Continuous UX flow monitoring. Describe critical user paths in plain English — Vigil runs them on a schedule with Playwright + Claude, auto-heals broken selectors, and alerts your team the moment something breaks.

Architecture

Clerk auth → FastAPI API → PostgreSQL  (orgs, flows, runs, alerts, locations)
                         → Redis       (selector cache for instant replay)
                         → Playwright  (headless browser execution)
                         → Claude      (step resolution + failure diagnosis)
                         → Resend      (email alerts + member invites)

## Local development

### Prerequisites

- Docker + Docker Compose
- Node 18+
- Python 3.11+

### 1. Environment variables

```bash
cp .env.example .env

Required values in .env:

Variable	Description
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string
CLERK_JWT_ISSUER	Clerk instance URL (e.g. https://xxx.clerk.accounts.dev)
ANTHROPIC_API_KEY	Claude API key
RESEND_API_KEY	Resend API key for alerts + invites
RESEND_FROM_EMAIL	Verified sender address
STRIPE_SECRET_KEY	Stripe secret key (optional, billing)
STRIPE_WEBHOOK_SECRET	Stripe webhook secret (optional)

2. Start infrastructure

docker compose up -d

Starts Postgres and Redis. Migrations run automatically on API startup.

3. Start backend

pip install -r requirements.txt
playwright install chromium
uvicorn backend.main:app --reload --port 8000

Or via Docker:

docker compose up -d --build api

4. Start frontend

cd frontend
cp .env.local.example .env.local
# Set VITE_CLERK_PUBLISHABLE_KEY from Clerk dashboard
npm install
npm run dev

Frontend runs at http://localhost:3000. Make sure CORS_ORIGINS in .env includes it.

Clerk setup

1. Create an app at clerk.com
2. Copy the Publishable key → VITE_CLERK_PUBLISHABLE_KEY in frontend/.env.local
3. Copy the JWT issuer URL → CLERK_JWT_ISSUER in root .env

---

How it works

1. Describe — write test steps in plain English (no selectors, no code)
2. First run — Claude navigates the app using accessibility snapshots, caches every selector to Redis
3. Replay — subsequent runs use cached Playwright actions at native speed, zero LLM calls
4. Auto-heal — when a UI change causes a cache miss, Claude re-discovers only that step and re-caches
5. Alert — failures trigger email/Slack alerts with the failed step, Claude diagnosis, and a screenshot

CI/CD integration

Generate an org API key from Settings → API Keys in the dashboard, then trigger a run from your pipeline:

curl -X POST https://your-api.com/api/flows/<flow_id>/run \
  -H "Authorization: Bearer <org_api_key>"