pixelcheck

<h1 align="center">PixelCheck</h1>

<p align="center">
  <strong>Real eyes and hands for the AI agent that's writing your frontend.</strong>
</p>

<p align="center">
  Drop-in MCP server. Five browser primitives. Eighteen personas across fifteen countries.<br/>
  Local-first &middot; Vendor-agnostic &middot; MIT-licensed &middot; Yours to own.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/pixelcheck"><img alt="npm" src="https://img.shields.io/npm/v/pixelcheck?color=cb3837&label=npm&logo=npm&logoColor=white"></a>
  <a href="https://www.npmjs.com/package/pixelcheck"><img alt="npm downloads" src="https://img.shields.io/npm/dm/pixelcheck?color=cb3837&logo=npm&logoColor=white"></a>
  <a href="LICENSE"><img alt="license" src="https://img.shields.io/github/license/xcodethink/pixelcheck?color=3da639"></a>
  <a href="https://modelcontextprotocol.io"><img alt="MCP" src="https://img.shields.io/badge/MCP-compatible-4f46e5"></a>
  <a href="https://github.com/xcodethink/pixelcheck/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/xcodethink/pixelcheck/ci.yml?branch=main&label=CI&logo=github"></a>
  <img alt="node" src="https://img.shields.io/node/v/pixelcheck?color=339933&logo=node.js&logoColor=white">
  <img alt="typescript" src="https://img.shields.io/github/languages/top/xcodethink/pixelcheck?color=3178c6&logo=typescript&logoColor=white">
  <a href="https://github.com/xcodethink/pixelcheck/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/xcodethink/pixelcheck?color=3178c6&logo=github"></a>
  <a href="https://github.com/xcodethink/pixelcheck/stargazers"><img alt="stars" src="https://img.shields.io/github/stars/xcodethink/pixelcheck?style=flat&color=ffd700"></a>
</p>

<p align="center">
  <a href="#quick-start"><b>Quick Start →</b></a>
  &nbsp;&middot;&nbsp;
  <a href="#primitives">Primitives</a>
  &nbsp;&middot;&nbsp;
  <a href="#mcp-server">MCP Server</a>
  &nbsp;&middot;&nbsp;
  <a href="#audit-preset">Audit Preset</a>
  &nbsp;&middot;&nbsp;
  <a href="#why-not-e2e-tests">Why Not E2E</a>
  &nbsp;&middot;&nbsp;
  <a href="CHANGELOG.md">Changelog</a>
</p>

---

> **If PixelCheck helps you, [give it a star](https://github.com/xcodethink/pixelcheck/stargazers) — it helps others discover the project.**

---

## Right now, you're a screenshotting middleman.

Your AI agent is writing 80% of your frontend. It's fast. It's good at code. But it's blind.

- **It writes a button.** You open Chrome to check it rendered right. Paste a screenshot back. Ask for the fix.
- **It tweaks the OAuth flow.** You log in to verify it didn't silently break. Again. Sixth time this month.
- **It updates the Japanese strings.** A user emails: "half the page is in English." You didn't catch it.
- **It rewrites checkout.** You walk through it on iPhone, Android, iPad just to *feel* whether step 3 is confusing.
- **It changes the Arabic layout.** RTL didn't propagate. You don't notice for two days.

You become the bridge. The agent has thoughts. You have a browser. **The two never meet.** Hours of your week, every week, indefinitely.

<a id="primitives"></a>

## PixelCheck is the bridge.

A single MCP server. Five primitives. Drop it in once — your agent has eyes and hands.

```
see(url, opts)              snapshot a page (DOM + screenshot + console + network)
act(url, steps)             execute an action sequence (semantic + selector + Computer Use)
extract(url, schema)        pull structured data matching a Zod / JSON schema
judge(url, rubric)          score a page against a rubric ("is this dark-pattern free?")
compare(a, b, criteria)     A/B comparison of two URLs (incl. blind mode)
```

Now your agent navigates. Sees rendered HTML. Reads console errors. Clicks. Fills. Judges. Compares. **Without ever leaving its workflow** — drop into Claude Desktop, Cursor, Cline, Continue, Zed, or Claude Code via four lines in `~/.mcp.json`.

```bash
npm install -g pixelcheck        # browser binary auto-installs on install
pixelcheck doctor                # verify environment (--fix self-heals)
pixelcheck-mcp                   # MCP server (stdio transport)
```

```jsonc
// ~/.mcp.json
{
  "mcpServers": {
    "pixelcheck": {
      "command": "pixelcheck-mcp",
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}
```

Restart your client. Your agent has eyes.

## Three promises that aren't going anywhere.

**Local-first.** PixelCheck runs entirely on your machine. The only outbound network destination is the LLM provider your agent already uses. Screenshots, DOMs, business flows, OAuth tokens, customer URLs — they stay yours. Zero telemetry. Zero remote storage. Zero SaaS sign-up. The audit data hits Anthropic only when the vision critic actively scores a screenshot, and you opt in once on first run.

**Vendor-agnostic.** Works with Claude today; multi-provider abstraction (OpenAI, Gemini, Ollama-local) is on the v1.x Wave 2 roadmap and your agent will switch with one config flag. The reason is simple: AI tools that lock you to a single LLM provider die in 2026. PixelCheck is the antidote.

**Yours to own.** MIT license. Source-available. No paid tier. No "Pro" upgrade path. No commercial fork waiting in the wings. The 1858-test, 29-ADR, 30-published-schema product in this repo *is* the entire product. There's no premium edition behind a sign-up wall — never was, never will be.

---

<a id="audit-preset"></a>

## The Audit Preset — when *you* want to be the user, not the bridge

The five primitives compose into something more powerful when you're the operator: PixelCheck bundles an **18-persona / 15-country audit preset** on top of the primitives — a CLI-first composition that runs "eighteen real users review your product" after every deployment.

You deploy. Tests pass. CI is green. But then:

- A Japanese user opens your app and sees half-translated English strings mixed into the UI
- A user on a budget Android phone in Nigeria waits 12 seconds for your hero image to load
- Your OAuth login flow silently breaks — again — for the 6th time in 10 deployments
- The Arabic version renders left-to-right, making the entire layout unusable
- Your "Trusted" score badge shows green while the copy says "stop interacting immediately"

**No E2E test catches these.** They test whether code runs. They don't test whether the product *works* for real humans in real contexts.

The audit preset launches real Chromium browsers as 18 different users from 17 countries, walks through your product's core flows, and delivers a verdict — like having a senior PM, QA engineer, and UX reviewer audit every deployment, in every language, on every device class.

```bash
pixelcheck init projects/my-app --name "My App" --url "https://myapp.com"
pixelcheck run --project projects/my-app
```

**Output**: a structured report with per-step screenshots, video recordings, network logs, WCAG accessibility violations, and AI-scored ratings across 6 dimensions — served as JSON, HTML dashboard, or Markdown.

## How It Works

For each **(persona x scenario)** combination:

```
 1. Launch Chromium with device-accurate fingerprint
    (viewport, locale, timezone, UA, regional proxy)
                        |
 2. Execute scenario steps semantically via Stagehand 3.x
    ("click the sign-up button" not "click #btn-37")
                        |
 3. 5-Layer Reliability Stack ensures 98%+ step success
    Stability Gate -> LLM Rewrite -> Selector Discovery -> Auto Selector -> Computer Use
                        |
 4. Claude Vision Critic + axe-core score each checkpoint on 18 dimensions
    completion | localization | visual_polish | trust_signals | accessibility | ...
                        |
 5. Critical steps escalate to Computer Use for pixel-level review
                        |
 6. Generate report: JSON + HTML dashboard + Markdown + video + HAR
```

## Why Not E2E Tests?

| | Traditional E2E | PixelCheck (audit preset) |
|---|---|---|
| **What it tests** | Code logic | Product experience |
| **Decision making** | Hardcoded selectors | AI reads the page like a human |
| **Assertion style** | `expect(text).toBe("Welcome")` | *"As a Japanese free-tier user, is this CTA clear and fully localized?"* |
| **When UI changes** | Selectors break, tests fail | Semantic instructions adapt automatically |
| **Failure output** | Stack trace | Screenshots + video + 6-dimension score + specific UX issues |
| **What it catches** | Functional bugs | i18n gaps, UX friction, visual regressions, trust issues, accessibility violations, cultural mismatches |

**PixelCheck's audit preset is not a replacement for E2E tests.** It's what runs *after* them — the layer between "code works" and "product is good."

## Compared to existing tools

| | **PixelCheck** | Playwright | Cypress | Stagehand | Browserbase |
|---|---|---|---|---|---|
| **MCP server out of the box** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **Browser primitives an AI agent can call** | 5 (see / act / extract / judge / compare) | n/a (low-level page API) | n/a | 3 (act / extract / observe) | n/a |
| **AI vision (judge / critique)** | ✅ via Anthropic | ❌ | ❌ | ❌ (action-only) | ❌ |
| **Built-in personas** | 18 across 15 countries | ❌ | ❌ | ❌ | ❌ |
| **Localised report (5 languages)** | ✅ | ❌ | ❌ | ❌ | ❌ |
| **WCAG 2.x audit + SARIF export** | ✅ (axe-core + GitHub Code Scanning ready) | manual via plugins | manual via plugins | ❌ | ❌ |
| **Local-first by default** | ✅ (your machine, your API key) | ✅ | ✅ | ✅ (or Browserbase) | ❌ (cloud-only) |
| **Vendor lock-in** | none (MIT, no SaaS) | none | none | optional Browserbase | full (paid SaaS) |
| **LLM provider** | swap any (Anthropic default; primitives are vendor-agnostic) | n/a | n/a | swap any | n/a |
| **Open source** | ✅ MIT | ✅ Apache 2.0 | ✅ MIT | ✅ MIT | partial |

**TL;DR**: Playwright / Cypress are deterministic browser drivers — you tell them exactly what to click. Stagehand wraps Playwright with natural-languag