![\"npm\"](\"https://img.shields.io/npm/v/pixelcheck?color=cb3837&label=npm&logo=npm&logoColor=white\"){kind=tracking}
\n ![\"npm](\"https://img.shields.io/npm/dm/pixelcheck?color=cb3837&logo=npm&logoColor=white\"){kind=tracking}
\n ![\"license\"](\"https://img.shields.io/github/license/xcodethink/pixelcheck?color=3da639\"){kind=tracking}
\n ![\"MCP\"](\"https://img.shields.io/badge/MCP-compatible-4f46e5\"){kind=icon}
\n ![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/xcodethink/pixelcheck/ci.yml?branch=main&label=CI&logo=github\")
\n ![\"node\"](\"https://img.shields.io/node/v/pixelcheck?color=339933&logo=node.js&logoColor=white\"){kind=tracking}
\n ![\"typescript\"](\"https://img.shields.io/github/languages/top/xcodethink/pixelcheck?color=3178c6&logo=typescript&logoColor=white\"){kind=tracking}
\n ![\"release\"](\"https://img.shields.io/github/v/release/xcodethink/pixelcheck?color=3178c6&logo=github\"){kind=tracking}
\n ![\"stars\"](\"https://img.shields.io/github/stars/xcodethink/pixelcheck?style=flat&color=ffd700\"){kind=tracking}
\n\n Real eyes and hands for the AI agent that's writing your frontend.\n
\n\n\n Drop-in MCP server. Five browser primitives. Eighteen personas across fifteen countries.
\n Local-first · Vendor-agnostic · MIT-licensed · Yours to own.\n
\n
\n Quick Start →\n · \n Primitives\n · \n MCP Server\n · \n Audit Preset\n · \n Why Not E2E\n · \n Changelog\n
\n\n---\n\n> **If PixelCheck helps you, [give it a star](https://github.com/xcodethink/pixelcheck/stargazers) — it helps others discover the project.**\n\n---\n\n## Right now, you're a screenshotting middleman.\n\nYour AI agent is writing 80% of your frontend. It's fast. It's good at code. But it's blind.\n\n- **It writes a button.** You open Chrome to check it rendered right. Paste a screenshot back. Ask for the fix.\n- **It tweaks the OAuth flow.** You log in to verify it didn't silently break. Again. Sixth time this month.\n- **It updates the Japanese strings.** A user emails: \"half the page is in English.\" You didn't catch it.\n- **It rewrites checkout.** You walk through it on iPhone, Android, iPad just to *feel* whether step 3 is confusing.\n- **It changes the Arabic layout.** RTL didn't propagate. You don't notice for two days.\n\nYou become the bridge. The agent has thoughts. You have a browser. **The two never meet.** Hours of your week, every week, indefinitely.\n\n\n\n## PixelCheck is the bridge.\n\nA single MCP server. Five primitives. Drop it in once — your agent has eyes and hands.\n\n```\nsee(url, opts) snapshot a page (DOM + screenshot + console + network)\nact(url, steps) execute an action sequence (semantic + selector + Computer Use)\nextract(url, schema) pull structured data matching a Zod / JSON schema\njudge(url, rubric) score a page against a rubric (\"is this dark-pattern free?\")\ncompare(a, b, criteria) A/B comparison of two URLs (incl. blind mode)\n```\n\nNow 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`.\n\n```bash\nnpm install -g pixelcheck # browser binary auto-installs on install\npixelcheck doctor # verify environment (--fix self-heals)\npixelcheck-mcp # MCP server (stdio transport)\n```\n\n```jsonc\n// ~/.mcp.json\n{\n \"mcpServers\": {\n \"pixelcheck\": {\n \"command\": \"pixelcheck-mcp\",\n \"env\": { \"ANTHROPIC_API_KEY\": \"sk-ant-...\" }\n }\n }\n}\n```\n\nRestart your client. Your agent has eyes.\n\n## Three promises that aren't going anywhere.\n\n**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.\n\n**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.\n\n**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.\n\n---\n\n\n\n## The Audit Preset — when *you* want to be the user, not the bridge\n\nThe 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.\n\nYou deploy. Tests pass. CI is green. But then:\n\n- A Japanese user opens your app and sees half-translated English strings mixed into the UI\n- A user on a budget Android phone in Nigeria waits 12 seconds for your hero image to load\n- Your OAuth login flow silently breaks — again — for the 6th time in 10 deployments\n- The Arabic version renders left-to-right, making the entire layout unusable\n- Your \"Trusted\" score badge shows green while the copy says \"stop interacting immediately\"\n\n**No E2E test catches these.** They test whether code runs. They don't test whether the product *works* for real humans in real contexts.\n\nThe 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.\n\n```bash\npixelcheck init projects/my-app --name \"My App\" --url \"https://myapp.com\"\npixelcheck run --project projects/my-app\n```\n\n**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.\n\n## How It Works\n\nFor each **(persona x scenario)** combination:\n\n```\n 1. Launch Chromium with device-accurate fingerprint\n (viewport, locale, timezone, UA, regional proxy)\n |\n 2. Execute scenario steps semantically via Stagehand 3.x\n (\"click the sign-up button\" not \"click #btn-37\")\n |\n 3. 5-Layer Reliability Stack ensures 98%+ step success\n Stability Gate -> LLM Rewrite -> Selector Discovery -> Auto Selector -> Computer Use\n |\n 4. Claude Vision Critic + axe-core score each checkpoint on 18 dimensions\n completion | localization | visual_polish | trust_signals | accessibility | ...\n |\n 5. Critical steps escalate to Computer Use for pixel-level review\n |\n 6. Generate report: JSON + HTML dashboard + Markdown + video + HAR\n```\n\n## Why Not E2E Tests?\n\n| | Traditional E2E | PixelCheck (audit preset) |\n|---|---|---|\n| **What it tests** | Code logic | Product experience |\n| **Decision making** | Hardcoded selectors | AI reads the page like a human |\n| **Assertion style** | `expect(text).toBe(\"Welcome\")` | *\"As a Japanese free-tier user, is this CTA clear and fully localized?\"* |\n| **When UI changes** | Selectors break, tests fail | Semantic instructions adapt automatically |\n| **Failure output** | Stack trace | Screenshots + video + 6-dimension score + specific UX issues |\n| **What it catches** | Functional bugs | i18n gaps, UX friction, visual regressions, trust issues, accessibility violations, cultural mismatches |\n\n**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.\"\n\n## Compared to existing tools\n\n| | **PixelCheck** | Playwright | Cypress | Stagehand | Browserbase |\n|---|---|---|---|---|---|\n| **MCP server out of the box** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **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 |\n| **AI vision (judge / critique)** | ✅ via Anthropic | ❌ | ❌ | ❌ (action-only) | ❌ |\n| **Built-in personas** | 18 across 15 countries | ❌ | ❌ | ❌ | ❌ |\n| **Localised report (5 languages)** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **WCAG 2.x audit + SARIF export** | ✅ (axe-core + GitHub Code Scanning ready) | manual via plugins | manual via plugins | ❌ | ❌ |\n| **Local-first by default** | ✅ (your machine, your API key) | ✅ | ✅ | ✅ (or Browserbase) | ❌ (cloud-only) |\n| **Vendor lock-in** | none (MIT, no SaaS) | none | none | optional Browserbase | full (paid SaaS) |\n| **LLM provider** | swap any (Anthropic default; primitives are vendor-agnostic) | n/a | n/a | swap any | n/a |\n| **Open source** | ✅ MIT | ✅ Apache 2.0 | ✅ MIT | ✅ MIT | partial |\n\n**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.\n\n## Personas\n\n18 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.**\n\n| Persona | Country | Language | Device | Subscriber Tier (in your app) |\n|---|---|---|---|---|\n| US college student | US | English | iPhone 14 | Free |\n| Tokyo housewife | JP | Japanese | MacBook Pro | Pro |\n| Berlin security analyst | DE | German | iPad Pro | Power |\n| Shanghai student | CN | Chinese | Xiaomi Android | Free |\n| Sao Paulo freelancer | BR | Portuguese | Desktop | Free |\n| Riyadh businessman | SA | Arabic (RTL) | iPhone 15 Pro | Pro |\n| Mumbai office worker | IN | Hindi | Budget Android | Free |\n| Seoul designer | KR | Korean | QHD Desktop | Pro |\n| Hanoi student | VN | Vietnamese | Android | Free |\n| Moscow engineer | RU | Russian (Cyrillic) | Windows Desktop | Free |\n| Lagos entrepreneur | NG | English | Budget Tecno | Free |\n| Mexico City teacher | MX | Spanish (LATAM) | Android | Free |\n| Jakarta gig worker | ID | Bahasa Indonesia | Android | Free |\n| US retired teacher (72yo) | US | English | iPad | Free |\n| London security analyst | UK | English | Desktop | Power |\n| Paris marketing manager | FR | French | iPhone | Free |\n| Bangkok student | TH | Thai | iPhone SE | Free |\n| Taipei engineer | TW | Traditional Chinese | iPad | Pro |\n\nEach persona includes a **mental model** (who they are, what they expect) and **critical concerns** (what would make them lose trust). The AI reviewer judges your product *through their eyes*.\n\n**6 script systems**: Latin, CJK, Arabic (RTL), Cyrillic, Devanagari, Thai.\n\n## Scenarios Are Declarative YAML\n\nNo code required. Describe what a user does, not how to click:\n\n```yaml\nid: signup-flow\nname: New User Signup\npriority: P0\nsteps:\n - id: open-home\n type: visit\n url: https://myapp.com/${persona.url_locale}\n\n - id: click-signup\n type: act\n instruction: Click the sign-up or get-started button\n\n - id: check-language\n type: assert_visual\n instruction: |\n Is all visible text in ${persona.language}?\n Flag any English strings outside of brand names.\n\n - id: complete-oauth\n type: act\n instruction: Sign in with Google\n\n - id: verify-email\n type: check_email\n subject_contains: \"welcome\"\n timeout: 60000\n\n - id: a11y-check\n type: assert_a11y\n standard: wcag2aa # axe-core WCAG analysis\n exclude: [\".cookie-banner\"]\n\n - id: rate-onboarding\n type: assert_visual\n critical_review: true # escalates to Computer Use\n instruction: |\n Rate the post-signup experience. Is the value proposition\n clear within 10 seconds? Is the first action obvious?\n```\n\n**12 step types**: `visit`, `act`, `extract`, `observe`, `wait_for`, `assert_visual`, `assert_dom`, `assert_a11y`, `check_email`, `screenshot`, `computer_use`, `custom`\n\n## 5-Layer Reliability Stack\n\nAI-driven browsers are flaky (~75% baseline). We engineered that away:\n\n```\nLayer 1: Page Stability Gate +10% (zero cost)\n Wait for network idle + DOM stable + framework hydration\n |\nLayer 2: LLM Rewrite + Local Mutation +7% (~$0.001/call)\n Haiku rewrites failed instructions using DOM context;\n local rules rephrase/decompose/specify as fallback\n |\nLayer 3a: Selector Hint +3% (zero cost)\n Optional CSS selector fallback (manual or YAML-defined)\n |\nLayer 3b: Auto Selector Discovery +3% (zero cost)\n Stagehand observe() extracts candidate selectors automatically\n |\nLayer 4: Computer Use Fallback +2-4% ($0.01-0.15/call)\n Claude sees the actual pixels and operates the browser directly\n (Sonnet for non-critical steps, Opus for critical reviews)\n```\n\nTarget: **98-99% step success rate** across all persona/scenario combinations.\n\nEach step records which layer succeeded via `execution_method`, giving you a reliability breakdown per run.\n\n## Reports\n\nEvery audit produces a full evidence package:\n\n```\nreports/2026-04-11_post-deploy/\n |-- audit.json # Machine-readable, all scores and issues\n |-- audit.html # Dark-theme dashboard with trend sparklines\n |-- audit-explorer.html # Filterable SPA view of every (scenario × persona) — open with ?lang=zh-CN/ja/es/de for localised UI chrome\n |-- audit.pdf # Stakeholder-facing summary (A4, 12pt, vector text)\n |-- summary.md # Terminal-friendly overview\n |-- jp-japanese-pro-desktop__signup-flow/\n |-- 01-open_home.png # Timestamped screenshot\n |-- 02-check_language.png # + SHA-256 hash for each\n |-- network.har # Full network log\n |-- console.log # Browser console errors\n |-- video/*.webm # Session recording\n```\n\n`audit.json` and every MCP tool response carries a top-level `schema_version` field (SemVer). The contract is documented in [docs/contracts/RESULT_SCHEMA.md](./docs/contracts/RESULT_SCHEMA.md); machine-readable JSON Schemas live in [docs/schemas/](./docs/schemas/) and can be regenerated with `npm run schemas`.\n\n### WCAG compliance reporting\n\nThe `assert_a11y` scenario step runs [axe-core](https://github.com/dequelabs/axe-core) to detect accessibility violations. As of v1, every violation carries structured WCAG attribution that flows through to all stakeholder reports:\n\n- **PDF report** — a \"WCAG Compliance Summary\" section grouped by conformance level (A / AA / AAA), by the four WCAG principles (Perceivable / Operable / Understandable / Robust), and a top-violated-criteria table with deep links to the W3C Understanding documents.\n- **SARIF (GitHub Code Scanning / GitLab SAST)** — per-criterion ruleIds like `wcag/1-4-3`, `wcag/2-1-1`. Filter by W3C clause directly in the Security tab. Each rule's detail panel shows \"WCAG 1.4.3 Contrast (Minimum) (Level AA)\" with a link to the W3C spec.\n- **audit.json** — every accessibility issue gets `wcag_level` and `wcag_criterion` fields alongside the existing `description` / `recommendation`.\n\nCatalog covers WCAG 2.1 (the production-deployed standard) plus the 9 net-new success criteria added in WCAG 2.2 (e.g. 2.4.11 Focus Not Obscured, 2.5.8 Target Size). Compliance teams reading reports in zh-CN / ja / es / de see the section headings translated; SC names and id numbers (1.4.3, 2.1.1) stay canonical for compliance-document consistency.\n\nUse case — answering an RFP that asks \"Are you WCAG 2.1 AA compliant?\":\n\n```bash\npixelcheck run --project myapp # writes audit.pdf + audit.sarif\n# Open audit.pdf → \"WCAG Compliance Summary\" section shows A / AA / AAA counts\n# Or upload audit.sarif via github/codeql-action/upload-sarif → grouped under wcag/* ruleIds\n```\n\nSee [ADR-024](docs/decisions/ADR-024-wcag-clause-grouping.md) for the full design.\n\n### Localised reports\n\nStakeholder reports (PDF / trends dashboard / PR diff Markdown / PR diff HTML) emit in the language of your audience. v1 supports 5 locales:\n\n| Code | Language | Used for |\n|---|---|---|\n| `en` | English (default) | Baseline |\n| `zh-CN` | Simplified Chinese | China-market teams |\n| `ja` | Japanese | Japan-market product orgs |\n| `es` | Spanish | Spain + Latin America |\n| `de` | German | DACH-region enterprises |\n\n```bash\npixelcheck run --project myapp --locale ja # Japanese PDF + reports\npixelcheck trends --project myapp --locale zh-CN # Chinese trends dashboard\npixelcheck diff --format markdown --locale es # Spanish PR comment\n```\n\nOr pin a default in `config.yaml`:\n```yaml\nproject_name: myapp\nbase_url: https://myapp.com\ndefault_locale: ja # any audit run on this project defaults to ja\n```\n\nWhat's translated: report skeleton — section titles, table headers, status / severity badges, disclaimer prose. What's NOT translated: PixelCheck's findings themselves (those come from the LLM in whatever language you asked Claude for) and numeric values / dates / run IDs. See [ADR-023](docs/decisions/ADR-023-report-localisation.md) for the full design.\n\n**Translations reviewed by**: machine-assisted draft pending native-speaker review. We track reviewer credits publicly — see [docs/translation-review-template.md](docs/translation-review-template.md) and the [translation-review issue template](.github/ISSUE_TEMPLATE/translation-review.yml). Confirmed reviewers will be listed below as the v1.x review pass completes.\n\n| Locale | Reviewer | Date | Corrections applied |\n|---|---|---|---|\n| `en` | (source — no review needed) | — | — |\n| `zh-CN` | _pending_ | _pending_ | _pending_ |\n| `ja` | _pending_ | _pending_ | _pending_ |\n| `es` | _pending_ | _pending_ | _pending_ |\n| `de` | _pending_ | _pending_ | _pending_ |\n\n### PDF report (audit.pdf)\n\nA 4-section A4 portrait PDF aimed at the layer of decision-makers above engineering — PMs, executives, customers, sales / CS reps. The format every email client renders inline, every slide deck embeds, every phone opens.\n\n| Section | Contents |\n|---|---|\n| Cover | Project + URL + run date + colour-coded overall score (green ≥ 8, amber 5–8, red < 5) + 7-counter summary card |\n| Top findings | Severity-sorted (critical → high → medium → low), capped at 5; each cites scenario × persona context + recommendation |\n| Scenario results | One block per (scenario × persona): status badge, score + cost, per-dimension table, all issues |\n| Methodology | How the audit works, persona list, scenario list, calibration disclaimer, run id for archival |\n\nVector text (selectable / searchable / accessible) — not a screenshot of HTML. No screenshots embedded so the file stays under ~1 MB and emailable; for visual evidence, the recipient opens `audit-explorer.html` (cited in the methodology disclaimer).\n\nDefault: ON every run. Pass `--no-pdf` to skip during fast local iteration. See [ADR-020](docs/decisions/ADR-020-pdf-stakeholder-report.md) for the full design.\n\n### Historical Trends\n\nScores are tracked in a local SQLite database. Three ways to look at history:\n\n```bash\npixelcheck history # Terminal table of recent runs with scores\npixelcheck diff run_0412 run_0411 # Score deltas, new/resolved issues\npixelcheck trends # Full HTML dashboard with 5 charts (writes