Install UXRay in the agent loop.

MCP first, API ready. UXRay renders your frontend with Chrome/Playwright, returns screenshots and structured UX issues, then Codex or Claude Code repairs the UI and asks UXRay to score the diff.

Best first run

npm run demo:pipeline resets flawed fixtures, runs baseline eval, asks Codex to repair, reruns eval, and writes the report.

Real proof

The public gallery uses real screenshots from the same local eval pipeline: average score 39 → 100.

MCP tools

health_check, review_ui_url, and review_ui_diff.

Hosted limit

Cloudflare hosts docs, account shell, and API-shaped endpoints. Full rendering needs local MCP/Playwright or a browser-capable backend.

Fair demo setup

The screenshots were captured from the same fixture family, same local reviewer, same viewport contract, and same repair-loop prompt style. Baseline URL: 127.0.0.1:5182. After URL: 127.0.0.1:5183.

1. Install locally

git clone https://github.com/codepawl/ui-reviewer uxray
cd uxray
npm install
npm run typecheck
npm run build

If the repo is still private while testing, use the local project folder directly when registering MCP clients.

2. Add to Codex

codex mcp add uxray -- npm --prefix /absolute/path/to/uxray run mcp
codex mcp list
codex mcp get uxray

Prompt Codex with a narrow repair contract:

Use the uxray MCP server.
Call health_check.
Call review_ui_url on http://127.0.0.1:5173 with return_images=true.
Inspect the screenshots and structured issues.
Fix only the UI files needed.
Call review_ui_url again and compare before/after with review_ui_diff.

3. Add to Claude Code

claude mcp add uxray -- npm --prefix /absolute/path/to/uxray run mcp
claude mcp list

Use the uxray MCP server to review my local frontend URL.
Use screenshot evidence, high-severity issues, and the repair prompt as the edit contract.
After editing, rerun the review and summarize the score delta.

4. Install the UXRay agent skill

The skill tells coding agents when to call UXRay, how to avoid vague beautification, and how to complete the review → repair → diff loop without silly mistakes.

mkdir -p ~/.config/uxray/skills
curl -fsSL https://useuxray.com/plugins/uxray-agent-skill.md \
  -o ~/.config/uxray/skills/uxray-agent-skill.md

Skill rule of thumb: call UXRay before shipping any generated landing page, dashboard, onboarding flow, settings page, or pricing page.

5. Use the local API

npm run api
curl http://127.0.0.1:4317/health
curl -X POST http://127.0.0.1:4317/v1/reviews/url \
  -H 'content-type: application/json' \
  -d '{"url":"http://127.0.0.1:5173","use_vision":false,"return_images":false}'

Compare two saved reports:

curl -X POST http://127.0.0.1:4317/v1/reviews/diff \
  -H 'content-type: application/json' \
  -d @reports/demo/diff-request.json

6. Run the full demo

npm run demo:pipeline
npm run demo:report

Average score: 39 → 100
Total issues: 11 → 0
High severity: 9 → 0
Fixtures improved: 3/3

7. Plugins and hosted accounts

Account access should eventually unlock MCP config, plugin packs, saved reports, hosted review credits, and team rules. The current public account pages are a product shell until auth/billing are wired to the hosted backend.

MCP config

Copy-paste setup for Codex, Claude Code, and API clients.

UXRay skill

Agent instructions that prevent vague UI edits and enforce before/after proof.

Plugin packs

Rules for landing pages, dashboards, onboarding, docs, settings, and pricing.

Saved reports

Hosted history for screenshots, scores, issue deltas, and CI gates.

8. Pricing direction

Local MCP stays free. Hosted rendering is priced by review calls and bundled for teams. The paid API should run on Browserbase, Cloud Run, Fly.io, Render, or a controlled Playwright worker pool.