Set up Critter in your project

Critter is a local visual history tool for interface work. It serves your HTML prototype or starts your app, makes Git commits available as interactive versions, and lets you compare them in the browser. Your coding agent can handle the code and Git workflow while you review the results.

The package is @idamadam/critter on npm; the product website is critter.sh.

Before you install#

You need Node.js 18 or newer, npm, and Git. Your project must be in a Git repository and contain one of these:

• Plain HTML, CSS, and JavaScript that a browser can run directly.
• A Vite app.
• A Next.js app that can be statically exported.

For framework apps, have the project's package manager available: npm, Yarn, pnpm, or Bun. Critter runs the project's development, install, and build scripts on your machine, so use a repository you trust. HTML prototypes do not need a package.json or a build step.

Read supported projects and limitations if your app depends on a backend, authentication, or server rendering.

Install the CLI#

npm install -g @idamadam/critter

Give your agent the workflow#

If you are working with a coding agent, have it run this command and read the output:

critter skills get core

The installed CLI includes its matching workflow. It explains when to commit, how to compare versions, how to handle bookmarks, and when separate design alternatives are useful. Critter provides guidance and a viewer; your existing agent implements the designs.

You can also use Critter directly without an agent.

Setting up Critter as an agent#

If a person asked you to read this page and set up Critter, follow these steps from their project directory. Stop and ask before anything that would change their files or Git history.

1. Check the prerequisites: node --version (18 or newer), git --version, and git rev-parse --show-toplevel to confirm the project is in a Git repository.
2. Install the CLI with npm install -g @idamadam/critter, then confirm it with critter --version.
3. Run critter skills get core and read the whole output. It is the workflow that matches the installed version; follow it over anything on this page that disagrees.
4. Decide what to open. For plain HTML, use the page or directory the person wants to review. For Vite or Next.js, use the app directory, or --app <path> in a repository with several apps.
5. Run critter doctor with the same target (for example critter doctor prototypes/checkout.html or critter doctor --app apps/admin) and fix or report any failed check.
6. Start the viewer with critter view and the same target. It keeps running, so start it in a way that does not block you, and give the person the viewer URL it prints.

Do not create commits, branches or bookmarks just to set Critter up. Existing commits already appear in the viewer.

Open an HTML prototype#

From inside your Git repository, point Critter at the page you want to review:

critter view prototypes/checkout.html

Use your file's actual path. The Git repository becomes the website root, so the page can load shared assets and sibling pages. Working-file edits refresh automatically, and the selected page stays pinned when you switch or compare versions.

To serve a self-contained website directory instead:

critter view prototypes/

That directory becomes the website root, and the history only lists commits that changed it. Critter opens index.html when present, or shows a chooser for its HTML pages. Running critter view inside the directory has the same behavior. A detected Vite or Next.js app takes precedence; pass an HTML file explicitly when you want to review raw HTML.

Quote paths containing spaces, such as critter view "prototypes/Checkout flow.html". To check an HTML setup first, pass the same path to critter doctor, for example critter doctor prototypes/; HTML needs no package.json.

Open a Vite or Next.js app#

From the app directory, run:

critter doctor
critter view

Use critter view in place of your usual development command while reviewing. It starts the underlying dev server and prints a local viewer URL. Open that URL in your browser and keep the process running. While the dev server starts, the viewer says so; if it stops, the viewer shows its command, exit code and output, with a Restart dev server button.

For an app inside a larger repository, select it explicitly:

critter doctor --app apps/admin
critter view --app apps/admin

Replace apps/admin with your app's directory.

Work across projects and pages#

You can run viewers for several projects or apps at once; each chooses its own local ports. Running critter view again for the same app prints its existing viewer URL. Use critter view --new-instance when you deliberately want another viewer for that app.

To change the selected HTML page, run the file command again:

critter view prototypes/dashboard.html

Critter reuses the viewer for that website root and selects the new page.

Review your first iteration#

Critter frames your interface with a bar along the top, like a browser's toolbar, so nothing covers the page you are reviewing. The middle of the bar names the version on screen and whether it is the live interface or a past commit. Select it to open the history, where ordinary Git commits appear as earlier versions, grouped by day and week. Use the ← and → keys to step between versions.

HTML history uses committed files directly. A framework version builds when you select it; the viewer shows the build's steps as it goes, and its first build can take a minute or two. Prepared versions are cached for later review.

Select Compare in the bar to put the version on screen beside the live interface, or the live interface beside the version before it. You can also choose Compare on any row in the history. In a comparison you can change either side, turn on change highlights, synchronize interactions, and zoom.

To keep a version you may want to return to, bookmark it and say why. Make and commit useful design steps as part of your normal Git workflow. Descriptive commit subjects become useful version labels, such as “Add a Book button to free washers.”

Continue with comparing UI commits or exploring design alternatives with an agent. If setup fails, see troubleshooting.