![\"Verfix\"](\"https://verfix.dev/logo.png\"){kind=logo}
\n\n \n
\n Browser verification for AI coding agents.
\n Run deterministic browser flows, assert UI state, and get structured failure reports — all from a single CLI command.\n
\n ![\"npm](\"https://img.shields.io/npm/v/verfix.svg?style=flat-square&color=cb3837\")
\n ![\"npm](\"https://img.shields.io/npm/dm/verfix.svg?style=flat-square&color=blue\")
\n ![\"GitHub](\"https://img.shields.io/github/stars/verfix-dev/verfix?style=flat-square&color=yellow\")
![\"License\"](\"https://img.shields.io/badge/license-Apache%202.0-green.svg?style=flat-square\"){kind=icon}
\n ![\"Documentation\"](\"https://img.shields.io/badge/docs-verfix.dev-8A2BE2?style=flat-square\"){kind=icon}
\n Website · Docs · GitHub · Issues\n
\n\n---\n\n## What is Verfix?\n\nAI coding agents write code fast — but they can't verify that it actually works in a browser. **Verfix** bridges that gap.\n\nIt's a local-first runtime that gives coding agents deterministic browser verification. Define browser flows in JSON, run them from the CLI, and get structured pass/fail results that agents can parse and act on automatically. Everything runs in a single Node.js process on your machine — no Docker, no services.\n\n**No cloud. No accounts. No Docker. One command to start.**\n\n```\nnpx verfix init\n```\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js** 20+ (that's it)\n\n### 1. Initialize\n\nRun the interactive setup wizard in your project root:\n\n```bash\nnpx verfix init\n```\n\nThis will:\n- Detect your app's port automatically\n- Ask for the verification mode (default `strict` — fully deterministic, no AI key needed)\n- Download Chromium if needed (~130MB, one-time, cached in `~/.cache/ms-playwright`)\n- Scaffold `verfix.config.json` with starter flows\n- Create/update `AGENTS.md` with verification instructions for coding agents\n\n### 2. Run a flow\n\n```bash\nnpx verfix run --flow login --output json\n```\n\nOutput:\n\n```json\n{\n \"passed\": true,\n \"failures\": [],\n \"timeline_url\": null,\n \"trace_path\": \"/your/project/.verfix/runs/exec_abc123_trace.zip\",\n \"show_command\": \"verfix show exec_abc123\",\n \"detail_commands\": {\n \"console\": \"verfix show exec_abc123 --console --output json\",\n \"network\": \"verfix show exec_abc123 --network --output json\"\n },\n \"duration_ms\": 3120,\n \"retry_count\": 0,\n \"exit_code\": 0,\n \"execution_id\": \"exec_abc123\"\n}\n```\n\n### 3. Open the recorded trace\n\n```bash\nnpx verfix show exec_abc123 # or just `verfix show` for the newest run\n```\n\nEvery run records a full Playwright trace — screenshots of each step, network\nrequests, and console output — persisted under `.verfix/runs/` (newest 20 kept).\n\n---\n\n## Commands\n\n### `verfix init`\n\nInteractive setup wizard. Configures the runtime, scaffolds flows, and generates `AGENTS.md`.\n\n```bash\nverfix init\n```\n\n### `verfix show`\n\nOpen the Playwright trace viewer for a run (newest run if no id given).\n\n```bash\nverfix show # newest run\nverfix show exec_abc123 # specific run\n```\n\n### `verfix status`\n\nCheck your setup at a glance.\n\n```bash\nverfix status\n# Runner: local (no Docker needed — use --server for the container runtime)\n# Config: verfix.config.json\n# Chromium: installed\n# Last run: passed exec_abc123 (verfix show exec_abc123)\n```\n\n### `verfix run`\n\nExecute a verification flow and get structured results.\n\n```bash\n# Run a specific flow from verfix.config.json\nverfix run --flow login --output json\n\n# Run with pretty terminal output\nverfix run --flow login --output pretty\n\n# Override URL and mode\nverfix run --flow checkout --url http://localhost:5173 --mode strict\n\n# Show the browser window\nverfix run --flow checkout --show-browser\n\n# Run against a custom config\nverfix run --config path/to/verfix.config.json --flow signup\n```\n\n| Flag | Description | Default |\n|------|-------------|---------|\n| `-f, --flow