# 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](https://www.npmjs.com/package/@idamadam/critter); the product website is [critter.sh](https://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](/docs/supported-projects/) if your app depends on a backend, authentication, or server rendering.

## Install the CLI

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/docs/agent-workflow/#bookmark-versions-worth-keeping) 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](/guides/compare-ui-commits/) or [exploring design alternatives with an agent](/guides/explore-design-variations/). If setup fails, see [troubleshooting](/docs/troubleshooting/).

---

Canonical page: https://critter.sh/docs/getting-started/