Critter

A Git-native visual review loop for designers working with coding agents.

Critter turns ordinary commits into interactive versions of your app. Coding agents can handle the implementation and Git mechanics; designers can see how the interface changed, compare iterations side by side, and decide what to keep.

There is no separate checkpoint system. Agents commit meaningful iterations normally, and Critter turns that history into something you can review.

During interface work, Critter serves your HTML prototype or starts your app's dev server. It keeps the live interface available as the current version and adds visual history and comparison around it.

Quick start

Critter requires Node.js 18 or newer and Git. It supports plain HTML prototypes, Vite projects, and statically exportable Next.js projects.

npm install -g @idamadam/critter

Have your coding agent load Critter's version-matched workflow:

critter skills get core

Critter does not run the agent. The guidance shows an agent how to record visual iterations, keep alternative directions comparable, and use the Critter CLI without creating a parallel history.

From your project:

critter view

For a plain HTML prototype, run the command from inside its Git repository and point at the page you want to review:

critter view prototypes/checkout.html

Critter serves the Git repository as the website root, so the selected page can load shared CSS, JavaScript, images, and sibling pages. No package.json, dependency installation, or build command is required. Working files refresh automatically; historical previews use the committed files. The selected page path stays pinned when switching versions or comparing them. Missing historical pages return an explanation instead of showing a different page.

You can also select a website directory with critter view prototypes/. That directory becomes the website root. Critter opens index.html when present; otherwise it shows a chooser for the HTML pages in the directory. Run critter view inside such a directory for the same behavior. Vite and Next.js projects retain precedence when detected through their package dependencies.

To review another page in the same repository, run the file command again:

critter view prototypes/dashboard.html

Critter reuses the running viewer for that website root and selects the new page. Choosing a page from the directory chooser also pins it across versions and comparison panes. Quote paths containing spaces:

critter view "prototypes/Checkout flow.html"

Static previews exclude hidden files (including .git and .env), symlinks, node_modules, and private-key files. Historical versions include committed assets only. External resources still depend on their remote hosts.

For Vite and Next.js, use critter view instead of npm run dev while designing. Critter starts the underlying app server, then prints a local viewer URL. The live app appears as the current version; previous commits appear as earlier versions.

For a repository containing more than one app:

critter view --app apps/admin

You can run Critter for several projects or apps at once. Each viewer chooses its own local control and preview ports automatically. Running critter view again for the same app prints the existing viewer URL; use --new-instance when you deliberately want another viewer for that app.

For Vite and Next.js, Critter runs the selected project's scripts locally, so use it with repositories you trust.

Review the agent's work

Commit subjects become labels in Critter's history. Ask the agent to describe the design change, not only the implementation:

git commit -m "Make plan comparison easier to scan"

Critter frames your app with a bar along the top, like a browser's toolbar, so nothing covers the interface you're reviewing. The middle of the bar names the version on screen and whether it is the live app or a past commit; select it to open the history. Use the ← and → keys to step through versions, and Compare to put the version on screen beside the live app, or the live app beside the version before it.

Open the history to move between the live app and previous commits. Historical versions are prepared when you select them, then remain cached for faster review. HTML prototypes use committed files directly; framework apps run their build.

Bookmarks

Bookmark a version to come back to it. Hover a row in the history and select Bookmark, or select the bookmark in the bar (or press B) for the version on screen, then say why you're keeping it. The reason appears under the time; select it to edit it in place. Select the tinted bookmark to remove it (Undo is offered for a few seconds). When you choose a side to compare, bookmarked versions are listed first. Variations aren't bookmarked; their group already keeps them together.

Bookmarks are Git notes in refs/notes/critter: the note text is the reason, and an empty note is a bookmark without one. Your agent can add a bookmark when you ask, or find one from your description of it. Notes have their own history and do not change the annotated commit. They also use a separate ref, so share them explicitly when needed:

git push origin refs/notes/critter

Compare versions

Select Compare on any version to place it beside another commit or the live app.

In comparison mode you can:

• Change either the left or right version
• Zoom to 50%, 75% (the default) or 100%
• Highlight meaningful content, appearance, layout, and state changes
• Mirror scrolling, clicks, and form interactions between both versions
• Keep both versions on the same app route

Highlights are review aids based on the rendered page structure, not pixel-perfect image diffs.

To review a particular screen:

critter route /checkout

The route is applied to the live app and historical versions. If several viewers are running in the repository, run it from inside the app's directory or pass --app <path> to choose one.

Compare alternative directions

Most design work is a sequence of refinements, and ordinary commits are enough.

When a design question has genuinely different answers, an agent can develop each one on its own branch, named for the question and the answer:

git worktree add ../nav-compact -b critter/navigation/compact
git worktree add ../nav-editorial -b critter/navigation/editorial

Critter groups the branches under Navigation as one row in the history, marked with how many variations it holds. Selecting it opens the variation that changed most recently, and the bar becomes the group's switcher: the group's name, then a tab per variation to flick between them at the same route and scroll position. The tabs scroll sideways when there are more than fit, with the ones beyond the edge peeking in, and a count such as "3 of 7" sits between the arrows. The arrows, or [ and ], step through them; ← and → still step through one variation's commits.

A variation branched from another one is a remix. Critter shows where it came from, and Compare puts a remix beside its source. Comparing two variations of one group, each pane gets the switcher too.

After you choose a direction, the agent can apply it to the current working tree:

critter explore use navigation/editorial

This applies the variation's changes without moving HEAD. The working tree must be clean first.

Supported projects

Critter currently supports:

• Plain HTML/CSS/JavaScript prototypes in Git, including multiple HTML pages
• Vite projects
• Next.js projects that can be statically exported
• npm, Yarn, pnpm, and Bun for framework apps
• Single-app repositories and repositories containing multiple apps

Historical versions are stored as static snapshots in Critter's per-user cache outside the repository. HTML snapshots copy committed files without installing dependencies or compiling. The first build of a Vite or Next.js version may take a minute or two.

Static HTML mode expects files a browser can run directly. It does not compile TypeScript or JSX, resolve npm imports, or provide a backend. Keep using the framework workflow when your project needs those build steps. Remote assets and APIs are fetched from their current hosts; Git snapshots preserve local committed files, not external services.

For framework apps, historical builds omit values from your current .env.local, including variables with public-looking names. To pass a value deliberately, export it in the shell and name it explicitly: critter view --build-env VITE_API_URL. Repeat --build-env for additional variables. This affects historical builds; the live app still runs in your normal environment. Native builds execute as your user and are not a filesystem sandbox. Static HTML mode does not inject environment variables or use --build-env.

If something goes wrong

Check whether Critter can view the current project:

critter doctor

For an HTML preview with missing assets, check the website root: a file path uses the Git repository root, while a directory path uses that directory. Root-relative URLs such as /assets/style.css start there. Assets must be committed to appear in historical versions. If a page did not exist at a selected commit, choose a later version or another page.

Inspect a failed snapshot build:

critter logs <sha>

See all commands and options:

critter --help
critter view --help

Feedback and usage data

Tell Critter's maker what's working or not with the Feedback button in the viewer, or from the terminal:

critter feedback "What you'd like to share" [--yes|--no] [--email [email protected]]

Critter also sends anonymous usage data so its maker can see whether it installs, starts and gets used: that it was installed, whether the viewer started (with the framework and how long it took) or why it failed, and when versions are compared. Each event carries a random install ID, the Critter, Node and OS versions, and which coding agent ran it. It never includes code, file paths, repository, route or project names.

A short notice appears the first time Critter runs. Turn it off with any of:

critter telemetry off
DO_NOT_TRACK=1
CRITTER_TELEMETRY=0

It is always off in CI. critter telemetry shows whether it is on.

When the viewer starts, Critter also asks npm whether a newer version is out, at most once a day, and prints one line if there is. That request carries only the package name. It is off in CI and with DO_NOT_TRACK=1, NO_UPDATE_NOTIFIER=1 or CRITTER_UPDATE_CHECK=0.