UXRay

UXRay is a local-first UI/UX review gate for AI-built frontends. It gives coding agents a concrete repair contract instead of vague design advice:

health_check -> review_ui_url -> repair UI -> review_ui_diff

The public repo is the Apache-2.0 local MCP/core. The commercial cloud code has been split into the private codepawl/uxray-cloud repo.

What stays public

• MCP server: health_check, review_ui_url, review_ui_diff, check_update
• reviewer core and structured report schema
• local Playwright renderer
• optional vision adapter interface
• local HTTP API wrapper for development/smoke use
• eval fixtures and reproducible repair-loop demos
• agent auto-trigger rules for Codex, Claude Code-compatible MCP clients, and OMP
• public docs about the open-core/cloud boundary

What moved private

Private cloud/product code now lives in /home/nxank4/Code/hermes/codepawl/uxray-cloud and the GitHub private repo codepawl/uxray-cloud:

• Cloudflare Worker production control plane
• hosted account/session/dashboard code
• API-key issuance and hosted credit gates
• Creem checkout/webhook handling
• D1/R2 migrations and persisted report operations
• public production website/account/checkout assets
• hosted render deployment/runbooks and cloud smokes
• customer-data and internal admin workflows

Security should not rely on repo secrecy, but private cloud code keeps the public repo clean and reduces leaked business/infra assumptions. See SECURITY.md.

Install

git clone https://github.com/codepawl/uxray uxray
cd uxray
npm install
npm run typecheck
npm run build
npm run smoke:mcp

Run as MCP

npm run mcp

Codex:

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

Generic MCP JSON:

{
  "mcpServers": {
    "uxray": {
      "command": "npm",
      "args": ["--silent", "--prefix", "/absolute/path/to/uxray", "run", "mcp"]
    }
  }
}

Install agent rules locally:

npm run install:agents
npm run smoke:agents

Local API smoke

PORT=4317 npm run api
npm run smoke:api

The public API wrapper is for local development and smoke tests. Production account/dashboard/billing/hosted persistence lives in the private cloud repo.

Repair-loop proof

Run the deterministic fixture pack:

npm run eval:reset
npm run eval:fixtures
npm run demo:report

The validated demo loop from this repo showed:

average score: 39 -> 100
issues:        11 -> 0
high severity:  9 -> 0
fixtures: landing, dashboard, onboarding

Scripts

npm run typecheck
npm run build
npm run smoke:mcp
npm run smoke:render
npm run smoke:vision
npm run smoke:api
npm run eval:reset
npm run eval:fixtures
npm run demo:pipeline
npm run review:url
npm run review:diff
npm run check:update
npm run upgrade
npm run test:core
npm run install:agents
npm run smoke:agents

License

Apache-2.0. See LICENSE.

Cloud boundary

Keep these out of the public repo:

• .env and local secret stores
• Cloudflare/Wrangler/Creem tokens
• API keys, session cookies, magic-link tokens, OAuth tokens
• customer screenshots/private reports
• hosted render queues/fleet internals
• tenant isolation, billing reconciliation, abuse controls
• internal admin tooling and sensitive deployment runbooks

Thin public-safe abstractions are fine. Production cloud code belongs in codepawl/uxray-cloud.