Pixelcheck

PixelCheck

Real eyes and hands for the AI agent that's writing your frontend.

Drop-in MCP server. Five browser primitives. Eighteen personas across fifteen countries.

Local-first · Vendor-agnostic · MIT-licensed · Yours to own.

Quick Start → · Primitives · MCP Server · Audit Preset · Why Not E2E · Changelog

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.

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.

npm install -g pixelcheck        # browser binary auto-installs on install

pixelcheck doctor # verify environment (--fix self-heals) pixelcheck-mcp # MCP server (stdio transport)

// ~/.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 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.

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.

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) |

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

Why Not E2E Tests?

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

TL;DR: Playwright / Cypress are deterministic browser drivers — you tell them exactly what to click. Stagehand wraps Playwright with natural-language act / extract so an agent can drive a browser. PixelCheck is the next layer up: an MCP-shaped surface that gives any AI agent vision (see / judge / compare) on top of action (act / extract), with audit presets composed across personas. Use Playwright for unit-style tests; use Stagehand if you only need an agent to fill forms; use PixelCheck when the agent needs to *evaluate* a UI, not just operate it.

Personas

18 built-in personas covering real-world user diversity. The Subscriber Tier column is the persona's subscription level *in the SaaS you're auditing* (Free user / Pro subscriber / Power-user / enterprise) — used so PixelCheck can audit your product's tiered features (paywalls, upsells, gated UI, Pro-only flows). PixelCheck itself is MIT-licensed and 100% free with no paid tier or commercial fork.

| Taipei engineer | TW | Traditional Chinese | iPad