👻 ghost-qa

Autonomous headless browser QA & self-healing verification loop for coding agents.

Coding agents (Claude Code, Codex, Cursor, Windsurf) write code blind — then declare victory while the actual browser has React hydration errors, broken buttons, 500ing APIs, or mobile layout overflow.

ghost-qa fixes that. One command launches a headless browser against your running app, crawls the live DOM, safely pokes every button, traps runtime/network/layout failures, and hands the agent a structured Self-Healing Bug Report so it fixes its own bugs before telling you it's done.

npx -y ghost-qa test http://localhost:3000

No test scripts. No config. No mercy for "it works on my machine".

Prefer running straight from GitHub instead of npm? npx -y github:avivgerz-hue/ghost-qa test http://localhost:3000 works identically — every command in this README accepts either package source (ghost-qa mcp, ghost-qa init, …).

⚡ Quickstart

# 1. Start your app as usual
npm run dev            # → http://localhost:3000

# 2. Verify it in a real browser (one-time: downloads Chromium)
npx playwright install chromium
npx -y ghost-qa test http://localhost:3000

# 3. Teach your coding agent to do this automatically, forever
npx -y ghost-qa init

ghost-qa init installs .claude/skills/ghost-qa/SKILL.md and appends the strict "Verify in Browser Before Done" protocol to CLAUDE.md, AGENTS.md, and .cursorrules. From then on, your agent runs ghost-qa itself, fixes what it finds, and only reports completion on a PASS.

🔁 The Autonomous Self-Healing QA Loop

                        ┌──────────────────────────────────────────┐
                        │            CODING AGENT                   │
                        │  Claude Code · Codex · Cursor · Windsurf  │
                        └───┬──────────────────────────────▲───────┘
              writes code   │                                │  Self-Healing
                            ▼                                │  Bug Report
                    ┌───────────────┐              ┌─────────┴──────────┐
                    │   DEV SERVER   │              │  AGENT DIAGNOSTIC   │
                    │ localhost:3000 │              │  verdict · #ids ·   │
                    └───────┬───────┘              │  fix playbook       │
                            │ serves live DOM      └─────────▲──────────┘
                            ▼                                │ Markdown / JSON
                    ┌────────────────────────────────────────┴──────────┐
                    │                   👻 ghost-qa                      │
                    │                                                    │
                    │   Route Crawler ──► Interaction Runner             │
                    │        │                    │                      │
                    │        ▼                    ▼                      │
                    │   ┌─────────┐  ┌──────────┐  ┌─────────┐          │
                    │   │ CONSOLE │  │ NETWORK  │  │ LAYOUT  │          │
                    │   │  A11Y   │  │  PERF    │  │ 5 TRAPS │          │
                    │   │  TRAP   │  │  TRAP    │  │  TRAP   │          │
                    │   └─────────┘  └──────────┘  └─────────┘          │
                    │   Desktop 1440×900  +  Mobile 390×844 (iPhone)     │
                    └────────────────────────────────────────────────────┘
                                          │
                          fix bugs ───────┘  re-run until ✔ PASS

1. The agent writes code and starts the dev server.
2. ghost-qa test crawls every internal route on desktop + mobile, exercising interactive controls.
3. Five traps capture everything the browser actually experienced.
4. Failures return as a token-efficient diagnostic; the agent fixes the root causes and re-runs.
5. The loop ends only at PASS — that's when the agent may tell you it's done.

🪤 The 5-Trap Engine

1. Console Trap — src/traps/console-trap.ts

• Uncaught pageerror exceptions with stack traces
• Unhandled promise rejections
• React hydration mismatches ("Text content did not match", "A tree hydrated but…")
• console.error (major) and console.warning (minor) — with dev-server noise ([vite], HMR, React DevTools banners) filtered out

2. Network Trap — src/traps/network-trap.ts

• HTTP 5xx API crashes (critical) and 4xx responses (major)
• Failed fetch/XHR requests and connection failures
• CORS-blocked requests with remediation guidance
• Broken static assets (JS/CSS/images/fonts) and missing favicons (minor)

3. Layout Trap — src/traps/layout-trap.ts

• Horizontal overflow: scrollWidth > innerWidth, with the offending elements named (critical on mobile)
• Zero-dimension interactive elements — buttons rendered at 0×0 that no human could tap
• Broken images (naturalWidth === 0)
• Missing <meta name="viewport"> on mobile

4. Accessibility Trap — src/traps/a11y-trap.ts (new in v1.1.0)

• Buttons and links with no accessible name (icon-only controls screen readers can't identify)
• Images missing alt attributes (descriptive alt, or alt="" for decorative)
• Form inputs with no associated label — a placeholder is not a label
• Missing document <title> and missing <html lang>

5. Performance & Asset Trap — src/traps/perf-trap.ts (new in v1.1.0)

• Slow page loads via Navigation Timing (DOMContentLoaded / load budgets, 2× = critical)
• Oversized resources (> 1MB single asset) and excessive total payload (> 3MB)
• Main-thread jank / layout-thrashing indicators from the Long Tasks API
• Render-blocking <head> resources and excessive DOM size

Plus a safety-first Interaction Runner: it fills forms with inert data ([email protected]), opens tabs/modals/menus, and clicks ordinary buttons — but never destructive ones (delete, checkout, pay, logout, publish… are blocked by a tested safety gate).

🔌 Native MCP Server (new in v1.1.0)

ghost-qa ships a zero-dependency Model Context Protocol server (JSON-RPC 2.0 over stdio), so MCP hosts can invoke browser verification as a native tool instead of shelling out:

npx -y ghost-qa mcp

npx -y ghost-qa init writes the ready-to-use .mcp.json entry for you (merging with any servers you already have):

{ "mcpServers": { "ghost-qa": { "command": "npx", "args": ["-y", "ghost-qa", "mcp"] } } }

Works with Claude Code, Claude Desktop, Cursor, Codex — any MCP host.

Docker / Glama: the repo ships a production Dockerfile whose entrypoint is the MCP server (node dist/bin/ghost-qa.js mcp). Registry introspection (initialize + tools/list over stdio) answers instantly with no Chromium present — a browser is only launched when a tool is actually called:

docker build -t ghost-qa .
docker run -i ghost-qa   # MCP JSON-RPC over stdin/stdout

🖥️ Zero-lifecycle testing with --server-cmd (new in v1.1.0)

Don't even start the dev server yourself — ghost-qa will spawn it, wait for the URL to respond, audit, and terminate the whole process tree afterward:

npx -y ghost-qa test http://localhost:3000 --server-cmd "npm run dev"

Pair it with --html ghost-qa-report.html for a self-contained, dark-mode visual evidence dashboard (routes, interactions, every trap finding per viewport) you can attach to CI artifacts or PRs.

📟 Example output

👻 ghost-qa — autonomous browser verification
Target: http://localhost:3000/
Duration: 8.4s · Viewports: desktop + mobile · Depth: 2

Routes crawled
  /                            Home                 [200] 3 issues
  /pricing                     Pricing              [200] ✓
  /dashboard                   Dashboard            [200] 2 issues

Coverage
  Routes visited:       3
  Interactions tested:  21 passed · 1 failed · 4 skipped (safety)
  Issues:               5 total — 2 critical, 3 major, 0 minor

Failures caught
  ✖ CRITICAL [console] React hydration mismatch: Text content did not match…
      ↳ / · desktop · #a91f03cc
  ✖ CRITICAL [network] Server error HTTP 500 for /api/users — backend/API is crashing on this route.
      ↳ /dashboard · mobile · #51bd77e0
  ▲ MAJOR [layout] Horizontal overflow on mobile: page scrolls sideways by 130px…
      ↳ / · mobile · #c04d19aa

✖ GHOST-QA FAIL — blocking browser failures found. Fix them and re-run before reporting done.

The agent-facing report (--report ghost-qa-report.md) groups the same bugs by route with a per-category fix playbook and the exact re-run command.

🚀 CLI reference

test flags

Works with any stack that serves HTML on localhost — Next.js, Vite, Remix, Astro, Create React App, plain static servers, Rails, Django… if a browser can open it, ghost-qa can judge it.

🤖 The Agent Skill

SKILL.md (repo root) is the master skill. npx -y ghost-qa init installs it for:

• Claude Code → .claude/skills/ghost-qa/SKILL.md + protocol in CLAUDE.md
• Codex / generic agents → protocol in AGENTS.md
• Cursor / Windsurf → protocol in .cursorrules

The protocol is wrapped in <!-- ghost-qa:start/end --> markers, so re-running init updates it in place without duplicating or clobbering your other instructions.

⚖️ Scope & limitations (read this — we mean it)

ghost-qa is a local development verification tool, and we'd rather be honest than viral:

• Not a WCAG audit. The Accessibility Trap catches common machine-checkable failures (names, alt, labels, title, lang). Full WCAG conformance still needs assistive-technology testing.
• Not a replacement for your test suite. It complements unit/E2E tests by checking the live app the way a browser experiences it — it writes no persistent tests for you.
• Heuristic safety. The Interaction Runner refuses destructive-looking controls (delete, checkout, pay, logout…) and fills only inert data, but "destructive" is ultimately a word list. It is designed for localhost dev servers.
• Auth-gated apps. Without credentials, ghost-qa audits what an anonymous visitor sees (often the login page). Authenticated crawling is on the roadmap, not in the box today.
• Performance numbers are local-machine heuristics. Borderline perf findings on a loaded CI box deserve a re-run, not a panic.
• Never point it at production systems or sites you don't own or have explicit permission to test. It clicks real buttons.
• The MCP server is stdio-only (no network ports). Only wire it into MCP hosts you trust.

Found a trap flagging a healthy page? That's our most valuable issue type — file it with the report attached. Security reports: see SECURITY.md. Release history: CHANGELOG.md.

🧑‍💻 Development

npm install
npx playwright install chromium
npm run build     # tsc → dist/
npm test          # Vitest: trap evaluators, crawler policy, safety gate, reporters
node dist/bin/ghost-qa.js doctor

See CONTRIBUTING.md for the "pure evaluator first" architecture rules.

📄 License

MIT © VibeFoundry — see LICENSE.

Part of the VibeFoundry Agent Suite