pixelwise

Audit any web page like a design review. Contrast, spacing, alignment, accessibility and copy, with the evidence drawn on the page.

npx pixelwise https://your-site.com

Run

npx pixelwise https://your-site.com   # check a page, write one HTML report
npx pixelwise ./dist --deep           # a local build, every page of it
npx pixelwise setup                   # (re)run the first-run setup: AI, browser, statistics

Needs Node 22+ and a Chromium: the first run offers to download one (pixelwise install-browser); a system Chrome or Edge works too (--channel chrome).

It writes one self-contained file, ./pixelwise-report/<host>-<time>.html: the captured page, the data, screenshots, images and fonts are inside, nothing else is written. Open it by double click or send it to someone; --open opens it, --serve serves it, --out file.html or --out dir/ chooses where.

What you get

• Checks for accessibility, layout and spacing, type and copy, states and motion, your design system (--design-system), SEO and performance. Each finding has the measured value beside the expected one, a picture and a fix to copy.
• The report shows the page as captured with the panel beside it, plus wireframe, inspect, measure, a style editor and a stress test.
• --deep crawls the site (--max-pages, --scope, --include, --exclude) and adds a site overview with template-level problems first.
• AI triage sorts findings into fix, fine and unsure. It never adds or removes findings.
• --source . links findings to files and lines; --fix lets your agent fix them in a separate git worktree on a new branch, then re-checks.

pixelwise --help lists every option. pixelwise scan also writes JSON, SARIF or Markdown.

Exit codes: 0 ok, 1 findings over --gate (default warning), 2 usage or setup error, 130 cancelled.

CI (GitHub Actions):

- run: npx pixelwise scan $URL --format sarif --out pixelwise.sarif --gate error
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with: { sarif_file: pixelwise.sarif }
- run: npx pixelwise $URL --ci --out pixelwise-report/
  if: always()
- uses: actions/upload-artifact@v4
  if: always()
  with: { name: pixelwise-report, path: pixelwise-report/ }

Pages behind a login

npx pixelwise login https://app.example.com   # sign in by hand in a real window; saves ./pixelwise-auth.json
npx pixelwise https://app.example.com/orders --cookies pixelwise-auth.json

--cookies reads a Netscape cookies.txt (curl, wget, "Get cookies.txt"), a Cookie-Editor or EditThisCookie JSON export, or a Playwright storageState; it can be repeated. Also --cookie "name=value", --header "Authorization: Bearer …" (sent to the checked site only, never to CDNs or analytics) and --basic-auth user:pass; PIXELWISE_COOKIES and the config keys cookies, headers, basicAuth do the same, and pixelwise mcp --cookies lets an agent audit signed-in pages. Values never appear in the report, logs or statistics, and such a page sends no page text to the hosted AI. The login file is a key to your account: keep it out of git. With no display, export the cookies with a browser extension instead of login.

AI

On by default, answers cached; the source is chosen in this order:

| Source | How | Cost | Gets | |---|---|---|---| | Claude Code / Codex / OpenCode | chosen in pixelwise setup, or --ai-cli claude | your subscription | findings, screenshots, your source with --source | | OpenRouter | OPENROUTER_API_KEY or --ai-key | your key | findings and page text | | Vercel AI Gateway | AI_GATEWAY_API_KEY | your key | findings and page text | | Hosted | nothing to set | free, daily quota | findings; redacted page text for public URLs only; never screenshots or source |

A local agent runs on your own subscription, so it is used only once you choose it: a run without setup, without a terminal or with --yes never picks it by itself. --no-ai or PIXELWISE_AI=0 turns the AI off.

Coding agents (MCP)

pixelwise mcp lets an agent audit a page in a real browser and read findings, screenshots, styles and source (read-only).

claude mcp add pixelwise -- npx -y pixelwise mcp

# Codex: ~/.codex/config.toml
[mcp_servers.pixelwise]
command = "npx"
args = ["-y", "pixelwise", "mcp"]

// Cursor: .cursor/mcp.json
{ "mcpServers": { "pixelwise": { "command": "npx", "args": ["-y", "pixelwise", "mcp"] } } }

Append "--source", "." to link findings to your code, or --run report.html to serve a report you already have.

What leaves your machine

Pages are checked locally. What goes over the network:

• The AI review, to the source in the table above, with only what the table says. The hosted service is the last choice; it prints a one-line notice on each run until you run pixelwise setup, and knows your install only by an anonymous install token (random, created on first use).
• Anonymous per-rule statistics, on by default: counts and closed words (which rules fired, how many elements passed, what the AI or you decided, whether a fix worked), timings, the CLI version and the operating system, plus three identifiers: the same anonymous install token; a hash of the page's address pattern, salted on your machine, so only your install can tell two scans of one page apart; and a hash of the site's registrable domain (never for localhost, IP addresses or private host names), which the service hashes again with a secret key and lists only for sites checked by at least 5 installs. Never page text, addresses, selectors, source, file names, screenshots or keys. The first run prints this once; the send never blocks a run (capped at 3 seconds). Turn it off with any of: --no-telemetry, PIXELWISE_TELEMETRY=0, DO_NOT_TRACK=1, or "telemetry": false in the config file. CI does not disable it by itself.
• Updates: once a day the CLI asks the npm registry for the latest version (nothing about you or your pages is sent). A global install then updates itself in the background with the package manager that installed it, and pnpm dlx / yarn dlx / bunx re-run as the newest version; pixelwise update --auto notify only tells you, pixelwise update --auto off or PIXELWISE_NO_UPDATE_CHECK=1 stops both, and CI never checks.
• The browser download (only when no Chrome, Edge or Chromium is found), from Playwright's CDN.

Settings and the install token live in your OS config directory (XDG on Linux, %APPDATA% on Windows, ~/Library/Application Support on macOS); pixelwise setup prints the path.

Troubleshooting

• No browser found: it looks for Chrome, Edge and Chromium, or run npx pixelwise install-browser. Missing libraries on Linux: sudo npx playwright install-deps chromium-headless-shell.
• Node below 22: install a current LTS.
• Old version: pixelwise update (or pixelwise update --check); a global install updates itself in the background, npx always fetches the latest.
• Behind a proxy: set HTTPS_PROXY (the AI and the statistics use it on Node 22.21+ / 24.5+). The browser download uses the npmmirror copy automatically only with a mainland-China locale or time zone; elsewhere set PIXELWISE_DOWNLOAD_MIRROR=1 to try it, or PLAYWRIGHT_DOWNLOAD_HOST for a mirror of your own.
• A slow page: --timeout 60s gives it more time to load (default 30 s). --max-pages, --page-timeout and the other crawl limits only work with --deep.
• localhost fails: the dev server has to be running. ERR_UNSAFE_PORT means Chromium blocks that port; use another one.

像做设计评审一样检查任何网页：对比度、间距、对齐、无障碍与文案，证据画在页面上。

npx pixelwise https://your-site.com   # 检查页面，写出一个 HTML 报告
npx pixelwise ./dist --deep           # 本地构建产物，检查全部页面
npx pixelwise setup                   # 选择 AI 和浏览器（可选）

需要 Node 22+ 和一个 Chromium（首次运行会提示下载）。报告是单个 .html 文件，双击即可打开。--lang zh 使用中文界面，--no-ai 关闭 AI，--source . 把问题对到源码，--fix 让你的 agent 在独立 worktree 里修，pixelwise mcp 供 Claude Code / Codex 等编程 agent 调用。本机 agent 只在你选择后使用（pixelwise setup 或 --ai-cli）。匿名统计（含匿名安装令牌、网站域名哈希）的关闭方式：--no-telemetry 或 PIXELWISE_TELEMETRY=0。