SkillAgentSearch skills...

ghost-qa

Autonomous headless Playwright QA agent & MCP server. Crawl localhost or staging URLs across Desktop, Tablet & Mobile to catch broken flows, console errors & layout bugs.

Install / Use

claude mcp add avivgerz-hue -- npx -y github:avivgerz-hue/ghost-qa

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

79/100

Category

Automation

Supported Platforms

Claude Code
Claude Desktop
Cursor

Our assessment of ghost-qa

ghost-qa scores 79/100 on our quality scale, 2485th of 2,763 Automation skills we index.

Its MCP Server is 23 KB long, well organised into 33 sections with 12 code examples: a thorough specification that gives an agent plenty to work with.

It has 45 GitHub stars, so there is little community track record yet; judge it on its content.

Substance
30/30
Structure
20/20
Description
15/15
Adoption
7/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated yesterday, so ghost-qa is actively maintained.
  • It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 97/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.

ghost-qa compared with similar skills

All 4 of these similar skills score higher than ghost-qa; compare them before choosing.

SkillScoreStarsUpdatedFormat
ghost-qa (this skill)by avivgerz-hue79451d agoMCP Server
Agent-Reachby Panniantong100112.9k10d agoCLAUDE.md
hyperframesby heygen-com10086.2ktodayCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.md
headroomby headroomlabs-ai10080.0ktodayCLAUDE.md

Frequently asked questions

How do I install ghost-qa?
Run claude mcp add avivgerz-hue -- npx -y github:avivgerz-hue/ghost-qa. The install tabs above show the steps for each supported agent.
Which AI agents does ghost-qa work with?
It is written for Claude Code, Claude Desktop and Cursor, as a MCP Server file. Other agents that read the same format can often use it too.
Is ghost-qa safe to use?
It is MIT-licensed and scores 97/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is ghost-qa still maintained?
The repository was last updated yesterday, so ghost-qa is actively maintained.

👻 ghost-qa

Autonomous headless browser QA & self-healing verification loop for coding agents. v2.1.1 — the 8-Trap Deep Browser Inspection Engine: 3 viewports × light/dark, QA Health Score (A+…F), interactive HTML dashboard, and regression diffing.

CI npm version npm downloads License: MIT Node >= 20 Powered by Playwright

⭐ If this tool helps your AI coding workflow, please give this repository a Star! It helps more developers discover the project.

🧰 The VibeFoundry Agent Suite

One command each — star all three and keep the whole suite free & maintained:

  • 🎨 unslop — UI Design DNA & Anti-Slop Engine (npx -y unslop-mcp@latest init)
  • 🛡️ vibe-shield — Security Scanner for AI Code (npx -y @vibefoundry/vibe-shield@latest scan .)
  • 👻 ghost-qa — Autonomous Headless Browser QA (npx -y ghost-qa@latest test http://localhost:3000)

Live Terminal Demo

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

ghost-qa terminal preview

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    │  │ 8 TRAPS │          │
                    │   │  TRAP   │  │  TRAP    │  │  TRAP   │          │
                    │   └─────────┘  └──────────┘  └─────────┘          │
                    │   Desktop 1440×900 · Tablet 768×1024 · Mobile 375×812 │
                    └────────────────────────────────────────────────────┘
                                          │
                          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 1440×900, Tablet 768×1024 and Mobile 375×812, in light + dark colour schemes, exercising interactive controls.
  3. Eight traps capture everything the browser actually experienced, scored into a deterministic QA Health Score (0–100, Grade A+…F).
  4. Failures return as a token-efficient diagnostic (GHOST-QA-REPORT.md + PATCH-PROMPT.md with exact selectors); the agent fixes root causes and re-runs.
  5. ghost-qa compare before.json after.json proves the fix: the loop ends only at score 95–100 (A+), zero critical/major remaining, and zero new regressions.

🪤 The 8-Trap Deep Browser Inspection Engine (v2.0.0)

1. Console & Framework Runtime 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…")
  • Duplicate-key warnings and Content-Security-Policy violations (new in v2)
  • console.error (major) and console.warning (minor) — with dev-server noise ([vite], HMR, React DevTools banners) filtered out

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

  • HTTP 5xx API crashes (critical) and 4xx responses (major)
  • Failed fetch/XHR requests, timed-out requests, and connection failures
  • CORS-blocked requests and failed CORS preflights with remediation guidance
  • Broken static assets, broken images (naturalWidth === 0), broken inline SVGs (0×0), >500KB unoptimized payloads, and missing favicons (minor)

3. Layout, Responsive Geometry & Collision Trap — src/traps/layout-trap.ts

  • Horizontal overflow: scrollWidth > innerWidth, with the offending elements named (critical on mobile)
  • Overlapping interactive elements via bounding-box collision math, with exact selectors + boxes (new in v2)
  • Touch targets < 44×44px on touch viewports (WCAG 2.5.5 / Apple HIG), clipped text, and off-screen interactives (new in v2)
  • Zero-dimension interactive elements — buttons rendered at 0×0 that no human could tap
  • Missing <meta name="viewport"> on mobile

4. Accessibility (WCAG 2.1 AA) & Keyboard Focus Trap — src/traps/a11y-trap.ts

  • 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
  • Real computed contrast ratios (getComputedStyle foreground vs effective background, WCAG formula) (new in v2)
  • Heading hierarchy (missing <h1>, h1→h3 skips) and automated Tab-order verification — simulated Tab presses catch invisible or dead focus states (new in v2)
  • Missing document <title> and missing <html lang>

5. Performance & Core Web Vitals Trap — src/traps/perf-trap.ts

  • Core Web Vitals: TTFB, FCP, LCP estimation, and CLS (Cumulative Layout Shift) (new in v2)
  • Slow page loads via Navigation Timing (DOMContentLoaded / load budgets, 2× = critical)
  • Oversized resources (> 1MB single asset), unoptimized >500KB images/scripts, and excessive total payload (> 3MB)
  • Main-thread jank / layout-thrashing indicators from the Long Tasks API
  • Render-blocking <head> resources, excessive DOM size (>1500 nodes) and DOM depth > 32

6. Safe Interactive & Link Integrity Trap — src/traps/links-trap.ts (new in v2)

  • Placeholder links (href="", href="#", javascript:void(0)) and dead anchors/routes found during crawling
  • Buttons inside <form> with no type (they silently become submit buttons)
  • Disabled/stuck interactive controls — all observational, this trap never clicks anything

7. SEO, Metadata & Social Graph Trap — src/traps/seo-trap.ts (new in v2)

  • <title> (missing, <10 or >60 chars), meta description, <html lang>, viewport meta, canonical tag
  • OpenGraph set (og:title, og:description, og:image) for link unfurls
  • Duplicate id attributes in the live, post-hydration DOM

8. Dark / Light Theme Emulation Trap — src/traps/theme-trap.ts (new in v2)

  • Every page also renders under colorScheme: 'dark' and 'light' emulation
  • Computed contrast is re-evaluated per scheme — invisible dark-mode text (dark-on-dark) is caught automatically and tagged with the failing scheme

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


📊 QA Health Score, Artifacts & Interactive Dashboard (new in v2)

Every run computes a deterministic QA Health Score (0–100) and Letter Grade (A+ … F): each trap starts at 100 and loses 25 per critical, 10 per major, 3 per minor finding; the overall score is the mean of the eight trap sub-scores (Console, Network, Layout, A11y, Performance, Links/UX, SEO/DOM, Theme Parity).

npx -y ghost-qa test http://localhost:3000 --out-dir ghost-qa-out --screenshots

| Artifact | Contents | | --- | --- | | report.json | Complete machine-readable telemetry: per-trap scores, viewport matrices, exact DOM selectors (#id, data-testid, CSS path) and bounding boxes | | GHOST-QA-REPORT.md | Human + agent Self-Healing Bug Report with root-cause analysis and the fix playbook | | PATCH-PROMPT.md | Copy-paste remediation prompt: every finding with selector, bounding box, parent-component hints and the compare loop | | report.html | Self-contained, zero-dependency, dark-mode interactive QA Dashboard: Grade hero (A+…F), 8-Trap Scorecard, Route & Viewport Matrix, filterable findings (severity/trap/viewport), embedded screenshots when captured |

🔀 Regression Diffing — ghost-qa compare / ghost_qa_compare (new in v2)

npx -y ghost-qa test http://localhost:3000 --json > before.json   # baseline
# …agent fixes the bugs…
npx -y ghost-qa test http://localhost:3000 --json > after.json    # re-audit
npx -y ghost-qa compare before.json after.json                    # Regression & Verification Delta Report

The delta matches findings by stable fingerprint id and reports scoreDelta, fixedFindings, newRegressions, remainingFindings — so a coding agent can prove its fix resolved the bug without introducing regressions. verified requires score ≥ 95, zero regressions and no blocking findings left. Also available as the ghost_qa_compare MCP tool.


🔌 Native MCP Server

ghost-qa ships a zero

Truncated for display — read the full file on GitHub.

Related Skills

View on GitHub
GitHub Stars45
CategoryAutomation
Updated1d ago
Forks5

Languages

TypeScript

Trust signals

97/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 info