reviz

See every UI iteration you and your AI agent make — the actual code diff and how it looked — on a local, non-destructive canvas.

Reviz runs as a sidecar beside your dev server. On every save it captures the code diff (the core) and a screenshot of your running app (the visual layer), stores them locally, and shows them in a viewer — plus an in-page dock on your app itself. Any two iterations are comparable. Session-scoped: on git commit the session is archived as a browsable version and a fresh one begins, so past commits stay explorable. Framework-agnostic — it observes from outside your module graph, so there's zero import or code change in your project.

Published as reviz-tool on npm; the command is reviz.

npm i -D reviz-tool
npx reviz init      # one-time setup wizard
npx reviz start     # run it beside your dev server

Then edit a watched file and browse:

• Your app at http://localhost:4280 → the in-page dock (a floating iteration bar on your own pages)
• http://localhost:4242 → the full viewer (grid + timeline, side-by-side compare, restore, version switcher)

Everything stays on your machine. The MCP and viewer servers bind to localhost only.

2-minute quickstart

1. Install (as a dev dependency, in your app's repo):

   npm i -D reviz-tool

2. Init — detects your framework/port, writes .reviz.config.json, installs an append-only post-commit hook (each commit archives the session as a version), and registers the MCP server with your agent (Cursor / Claude Desktop):

   npx reviz init          # interactive; or `--yes` for defaults, `--no-register` to skip MCP

3. Start it in its own terminal, next to your npm run dev:

   npx reviz start

4. Edit any watched file. Each save becomes an iteration. Browse http://localhost:4280 for the dock, or http://localhost:4242 for the viewer.

Screenshots need a browser: npm i -D playwright && npx playwright install chromium (Reviz works diff-only without it).

Commands

| Command | What it does | |---|---| | reviz init | Setup wizard: config, git hook, MCP registration, optional dock snippet + agent skill. --yes, --no-register. | | reviz start | Watcher + diff engine + MCP server + viewer + dock proxy, one foreground process. | | reviz stop | Stop a running reviz. | | reviz status | Session, iteration count, label mode, store size. --doctor runs full diagnostics. | | reviz versions | List kept commit versions — the archived sessions from past commits. | | reviz open | Open the viewer in your browser. | | reviz clear | Clear the current session (--yes to skip the prompt). Unlike a commit, this deletes — it does not archive. | | reviz uninstall | Reverse init — remove the hook, MCP registration, dock snippet, and skills. | | reviz update | Update reviz-tool to the latest version on npm. | | reviz feedback | Report a bug or feature request. Interactive readline flow; auto-attaches version/OS/Node/framework. Flags: --title, --type bug\|feature\|feedback, --open (browser). | | reviz telemetry | on, off, or status. Manage anonymous usage telemetry consent. |

reviz status --doctor checks ports, Playwright, the git hook, store size, and MCP registration — each with a fix hint. When a newer reviz-tool is published, Reviz surfaces a one-line notice in the CLI, viewer, and dock, all pointing at reviz update — it only notifies, it never auto-updates.

Configuration

.reviz.config.json in your project root. Every key is optional; defaults shown:

| Key | Default | Meaning | |---|---|---| | port | 3000 | Your dev server's port (what Reviz screenshots). | | watch | ["src/**/*.css","src/**/*.tsx","src/**/*.html"] | Globs to watch for saves. | | ignore | ["node_modules",".next","dist"] | Globs to never watch. | | snapshots | true | Capture screenshots (needs Playwright). false = diff-only. | | viewerPort | 4242 | The viewer UI. | | mcpPort | 4243 | The MCP server (http://127.0.0.1:4243/mcp). | | dock | true | Run the dock proxy. | | dockPort | 4280 | Browse your app here to get the in-page dock. | | clearOnCommit | true | Close the session on git commit (via the post-commit hook). | | keepHistory | true | On commit, archive the session as a browsable version instead of deleting it. | | historyLimit | 10 | How many commit versions to keep; older ones are pruned. | | debounce | 300 | Per-file save debounce (ms). | | viewport | { "width": 1440, "height": 900 } | Screenshot viewport. | | maxStoreSizeMB | 500 | Soft cap; over it, the oldest unlabeled iterations' content + screenshots are pruned (diffs kept; labeled work never dropped). | | maxFileSizeKB | 512 | Files larger than this are recorded event-only (no content/diff). | | label | "auto" | auto = your AI agent labels iterations via MCP; manual = you label them in the viewer. |

MCP tools (for your AI agent)

When label is "auto", Reviz never calls an LLM itself — your connected agent labels the iterations it causes. The MCP server exposes:

| Tool | Purpose | |---|---| | list_iterations | List iterations (filter by file / label / unlabeled / time). | | get_iteration_diff | Diff for one iteration (vs previous + vs session start), or a pairwise compare. | | capture_iteration | Manual checkpoint before a risky edit. | | restore_iteration | Preview, then (with confirm) restore a file to an earlier state — backs up current first. | | label_iteration | Label an iteration (manual labels are never overwritten by auto). | | get_file_history | One file's iteration timeline. | | clear_iterations | Clear the session (dry-run unless confirmed). |

reviz init registers the server in .cursor/mcp.json and Claude Desktop's config automatically.

How it works

• Watcher (chokidar) sees saves from outside your project — no imports, no plugins.
• Diff engine stores a unified diff vs the previous iteration and vs the session baseline, plus full content for exact restore.
• Snapshot engine (optional, Playwright) screenshots the rendered DOM, which is why it works across any framework.
• Store is a local SQLite DB under .reviz/ (auto-added to .gitignore).
• Commit versions — instead of deleting the session, a git commit archives it (tagged to the commit's sha + subject) so you can browse, compare, and restore from past commits in the viewer.
• Dock proxy serves your app with one injected script so the dock rides along on your real pages — your app's build and module graph are never touched.

Invariants: Reviz never modifies your source except via an explicit restore (which confirms and backs up first); all data stays local; nothing couples to your framework.

Telemetry

Telemetry is off by default. During interactive reviz init, you are asked once per machine — clearly, explicitly — whether you want to help improve the beta. The --yes flag skips the question and leaves telemetry unconfigured. You can change your choice at any time with reviz telemetry on|off|status.

What is collected (only if you opt in):

| Field | Description | |---|---| | userId | Random anonymous UUID, generated at consent time. Stored in ~/.reviz/telemetry.json. Never tied to you. | | projectId | Random anonymous UUID per project. Stored in .reviz/project.json (gitignored, survives reviz clear). Lets us count unique projects without identifying them. | | version | Reviz package version. | | os | process.platform — e.g. darwin, linux, win32. | | node | Node.js version string. | | framework | Auto-detected framework (e.g. next, vite, remix), lowercased. Omitted when not detected. | | event | first_run (sent once per machine, during init) or session_start (sent on each reviz start). | | ts | ISO timestamp. |

What is NEVER collected: your code, diffs, snapshots, file names, file paths, project names, git history, commit messages, any personal or identifying information, or your IP address.

Where the data goes: a Supabase Edge Function (crnznrykeoadjaflkavr.supabase.co/functions/v1/telemetry) writes to the reviz_usage table in the Reviz project. Service-role-only writes; no anon-insert policies.

Consent and identity files:

• ~/.reviz/telemetry.json — global, per-machine: { enabled, userId, firstRunSent }. Presence means a choice has been made; reviz init never re-asks.
• .reviz/project.json — per-project anonymous ID. Created only after consent.

reviz telemetry on      # opt in (or re-enable); reuses existing userId
reviz telemetry off     # opt out; stops all future events
reviz telemetry status  # show current state, IDs, endpoint, and event list

FAQ & troubleshooting

• Nothing is capturing. Is reviz start running (its own terminal)? Does watch in .reviz.config.json match the files you're editing? Run reviz status --doctor.
• No screenshots. The dev server is down, port is wrong, or Playwright isn't installed (npm i -D playwright && npx playwright install chromium). Diffs keep working regardless.
• The dock isn't on localhost:3000. By design — browse localhost:4280 (the proxy injects the dock there). For a framework layout, your agent can add the dock snippet to your root layout (the shipped Reviz skill knows how); plain-HTML entries get it from reviz init.
• Where did my iterations go after a commit? They're archived as a version, not deleted (keepHistory: true). Browse them with reviz versions or the version switcher in the viewer. Set keepHistory: false to delete on commit instead; only the newest historyLimit versions are kept.
• A newer version is available. Run reviz update. Reviz checks npm at most once a day in the background and never auto-updates; set REVIZ_NO_UPDATE_CHECK=1 (or CI) to silence the check.
• Port already in use. Change viewerPort / mcpPort / dockPort in .reviz.config.json. reviz status --doctor flags conflicts.
• npx reviz says it can't find the command. Make sure reviz-tool is installed (npm i -D reviz-tool); the binary is named reviz.
• reviz start says better-sqlite3 is not available. The iteration store uses better-sqlite3, an optional native dependency — so npm install succeeds even where its prebuilt binary is missing and the source build fails (e.g. CI/deploy images). On your dev machine, fix it with npm rebuild better-sqlite3, or reinstall without --omit=optional / --no-optional. reviz status --doctor checks for this.

License

MIT