UI Verify

---

What is UI Verify?

UI Verify is a hosted visual-testing service that plugs into your CI. On each PR it:

1. Captures your UI, from Storybook stories, from your existing Playwright or Vitest browser-mode tests via a drop-in capture SDK, or from finished screenshots your own harness already produces (native, mobile, React Native) uploaded straight for diffing.
2. Renders & diffs every state in the cloud against the baseline from your default branch.
3. Reports the verdict back as a GitHub check, and gates the PR on it.
4. Triages: a coding agent (Claude Code, Codex, and others) buckets real regressions vs. cosmetic noise and can accept new baselines in bulk, all over MCP.

This repository holds the open-source client packages, everything that runs in your repo. All rendering, diffing, and judging happens server-side; these packages only build a bundle, upload it over HTTP, and read back status, so each is safe to read, fork, and self-host against.

Quickstart

# 1. Install the CLI in your project
npm i -D uiverify

# 2. Point it at your account
export UIVERIFY_API_KEY=...        # from uiverify.ai

# 3. Build your Storybook, then upload; the exit code reflects the visual verdict
npm run build-storybook
npx uiverify upload --static-dir storybook-static

Already have screenshots? If your harness already produces them (Detox, Maestro, native snapshot tests, anything), upload the PNGs directly, no Storybook and no rendering required. UI Verify diffs, judges, and baselines them just the same:

npx uiverify upload --screenshots ./screenshots

This is how native, mobile, and React Native projects use UI Verify: each image is keyed by its path under the directory, so a screen maps to the same baseline every build, and you can upload only the screens you changed and carry the rest forward.

Prefer to drive it from your agent? Install the skills (below) and run /uiverify:setup-visual-testing. It detects your capture path, wires CI, and writes the first stories for you.

Mid-edit checks for coding agents: uiverify check

While an agent is editing, it can render just the stories it is touching and diff them against the real CI baseline on the fleet - a "would this pass" answer without waiting for CI:

npm run build-storybook
npx uiverify check --story 'components-button--*' --static-dir storybook-static

It renders only the stories you name (repeatable --story, globs or exact ids), posts no PR check, and never moves a CI baseline. A changed result is informational (exit 0) - review the pixels over the UI Verify MCP (get_build / render_diff_image) and accept in the dashboard or with accept_build to set a branch-scoped preview baseline, so your own accepted changes stop re-flagging on the next check. CI stays the only path to a main baseline.

Packages

Package	Install	What it does
uiverify	npm i -D uiverify	The CLI. uiverify upload is the CI uploader (Storybook bundle, Playwright/Vitest archive, or a directory of finished screenshots) - streams render progress and reflects the visual verdict in its exit code. uiverify check is the agent edit-loop check - renders just the stories you name against the real CI baseline, without posting a check or moving a baseline.
@uiverify/playwright	npm i -D @uiverify/playwright	The Playwright capture SDK. Swap @playwright/test for it and each test archives its final UI state (serialized DOM + resource bytes) for UI Verify to replay and diff.
@uiverify/vitest	npm i -D @uiverify/vitest	The Vitest capture SDK. Add uiverifyPlugin() to your Vitest config and each browser-mode test archives its final DOM (serialized DOM + resource bytes) for UI Verify to replay and diff; takeSnapshot() takes named snapshots instead.
@uiverify/skills	npx skills add, see below	Agent skills: SKILL.md workflows a coding agent runs in your repo to set up visual testing, author economical + deterministic stories, and triage builds. As a Claude Code or Cursor plugin, or a Gemini CLI extension, it also connects the UI Verify MCP server.
@uiverify/workflow-skills	Claude Code plugin, see below	The agentic-development loop we build UI Verify with: factory, design, review-loop, e2e-verify, babysit-pr, and the skills that tune it.

Agent skills

Install the skills into any coding agent with one command (skills.sh):

npx skills add uiverify/uiverify

Works in Claude Code, Cursor, Codex, Copilot, Gemini, and any agent that reads a skills folder. Add --list to pick individual skills, and run npx skills update to pull the latest.

Or, on Claude Code, install as a plugin so updates arrive automatically:

/plugin marketplace add uiverify/uiverify
/plugin install uiverify@uiverify

Either way, invoke them by name: /uiverify:setup-visual-testing, /uiverify:triage-visual-changes, and more. See packages/skills for the full list and a copy-in-by-hand alternative.

On Gemini CLI, install the same skills plus the MCP server as an extension, then log in once:

gemini extensions install https://github.com/uiverify/uiverify

In a Gemini CLI session, run /mcp auth uiverify and log in to UI Verify in your browser.

The agentic-development loop we build UI Verify with (factory, design, review-loop, e2e-verify, babysit-pr) is a second plugin in the same marketplace: /plugin install uiverify-workflow@uiverify, then /uiverify-workflow:factory. See packages/workflow-skills.

Triage over MCP

Connect the UI Verify MCP server and your coding agent (Claude Code, Cursor, Codex, and others) can pull a pull request's UI changes into the conversation, look at each diff, read the AI judge's verdict, and accept the intended baselines - without leaving the terminal.

claude mcp add --scope project --transport http uiverify https://uiverify.ai/mcp

If you installed the plugin above, it already connects this server, so skip the command and just log in from /mcp. Otherwise restart Claude Code after adding it, run /mcp, pick uiverify, and log in to UI Verify in your browser. You log in once and the connection reaches every project in every team you are a member of. --scope project writes it to your committed .mcp.json so the whole team gets it; the file holds no secret, since each teammate logs in with their own account. In Cursor, add { "mcpServers": { "uiverify": { "url": "https://uiverify.ai/mcp" } } } to .cursor/mcp.json and log in from its MCP settings. In Gemini CLI, the extension above connects it, and /mcp auth uiverify logs you in. Full guide: Triage visual changes from your coding agent.

The server is remote (streamable HTTP) - there is nothing to install or run. It exposes:

Tool	What it does
list_projects	List the projects you can access, with the projectId to pass when you have several
list_builds	List recent UI Verify builds
get_build	Get what changed in a build
list_build_stories	Page through a build's stories by status
get_pr_changeset	Get what a PR does to the UI vs its base branch
list_pr_stories	Page through the PR-vs-base changeset by kind
get_diff	Per-story diff detail with image URLs
render_diff_image	Fetch the actual pixels of a story image
review_diff	Accept, deny, or ignore one story's change
accept_build	Accept every changed story in a build

Examples

Complete, runnable projects under examples/ — one per capture path. Copy a folder, add a project API key, and it works.

Example	Capture path
examples/storybook	Storybook stories (no SDK, upload --static-dir)
examples/vitest	Vitest browser-mode tests with @uiverify/vitest
examples/playwright	Playwright end-to-end tests with @uiverify/playwright
examples/react-native	Finished screenshots (native / mobile / React Native) with upload --screenshots

The first three capture a slice of the same Shoppy storefront; the React Native one is a small Expo app driven by Maestro. Each folder has its own CI workflow.

Development

pnpm install
pnpm -r build        # CLI builds dist/uiverify.js, playwright builds dist/
pnpm -r test
pnpm -r typecheck

The CLI requires UIVERIFY_API_KEY and talks to https://uiverify.ai by default (override with --api-url / UIVERIFY_API_URL for self-host or local dev). See each package's README and DEVELOPMENT.md for internals.

License

MIT © UI Verify