# Explore design alternatives with coding agents

Critter lets you group different committed UI designs and compare the working results in your browser. Your coding agent develops each alternative on its own Git branch, usually in its own worktree, and Critter groups the branches by name. You flick between the designs, compare any two, and choose which direction to continue.

The included skill gives the agent a workflow for the setup and Git mechanics. Critter itself does not run agents, create the designs, or decide which is best.

![The Shared planner compared with its source, the Sun planner, in Critter. Each pane is headed by the Rooftop sun group's switcher, and the resident swap the remix adds is tagged New.](/images/solar-commons-variations.webp)

## Decide whether you need alternatives

Use ordinary commits for a sequence of refinements: adjust spacing, simplify a heading, then improve a control. Those versions already appear in Critter's history.

Use an exploration when the same design question has different possible answers. For a shared-solar app, that might mean planning each resident's bookings around the sun or showing the whole building's spare power. Developing both from a shared starting point makes the tradeoff easier to judge.

| Design question | Possible alternatives | Keep consistent |
| --- | --- | --- |
| How should residents share the rooftop sun? | A planner that moves bookings into sunny hours; a view of the building's spare power | The building's data, bookings, route, and interactions |
| How should someone choose a plan? | A comparison table; a guided recommendation | Prices, features, and the decision being made |
| How should a project overview work? | A dense list; a visual board | Project data and available actions |

Start with two or three alternatives that make different choices. You can add more after seeing what the first comparison teaches you, including remixes that build on one of the originals.

## Give your agent the workflow and a concrete brief

Install Critter and start it from a supported project. Plain HTML prototypes, Vite and statically exportable Next.js are supported; see [setup](/docs/getting-started/) and [compatibility](/docs/supported-projects/) for requirements.

```bash
npm install -g @idamadam/critter
critter skills get core
critter view
```

For a plain HTML page, replace the final command with `critter view prototypes/today.html`, using the path to your page inside its Git repository. Critter serves the committed HTML, CSS and JavaScript without adding a build tool.

Have your coding agent read the output of `critter skills get core`. Printing it in a terminal does not automatically load it into every agent's context.

A brief for the Solar Commons example:

> Read Critter's core skill. From the same committed baseline, develop two directions to help residents use the rooftop sun: a planner that moves bookings into sunny hours, and a view of the building's spare power. Keep the data and route the same. Use separate worktrees on the branches critter/rooftop-sun/sun-planner and critter/rooftop-sun/building-view, and review and commit only each direction's changes. Show me both in Critter so I can choose what to develop further.

The agent still needs the project's own build instructions and your authorization for its normal Git workflow. Critter provides a review surface around that work.

## Develop the alternatives separately

A worktree gives a Git branch its own working directory. That lets separate agents, or one agent switching between tasks, edit different directions without sharing the same checked-out files.

Start from the intended committed baseline in your original project directory. Name each branch `critter/<question>/<variation>`: the question is the group, and the variation is the proposed answer. The example names below should be new branches and unused sibling directories:

```bash
git status --short
git worktree add -b critter/rooftop-sun/sun-planner ../rooftop-sun-planner HEAD
git worktree add -b critter/rooftop-sun/building-view ../rooftop-sun-building HEAD
```

Review any existing uncommitted work before proceeding. Both commands above run from the original project, so each direction starts at the same `HEAD`.

The branch name is the registration; no Critter command is needed. A variation appears in the viewer as soon as its branch exists and shows its latest commit once it has one. Avoid vague names such as `critter/cards/v2`.

Develop the planner in `../rooftop-sun-planner` and the building view in `../rooftop-sun-building`. For framework apps, install dependencies in each worktree using the project's package manager and check that each app builds. For plain HTML, check the page and local asset paths directly; no install or build step is needed. Commit each completed alternative in its own worktree. Worktrees share repository history, but do not share an installed `node_modules` directory.

## Remix a direction

Once the first directions exist, you may want a new one that builds on one of them: the sun planner with the names of who booked what, say. Branch the remix from the variation it builds on, not from the baseline:

```bash
git worktree add -b critter/rooftop-sun/shared-planner ../rooftop-sun-shared critter/rooftop-sun/sun-planner
```

Critter reads where a variation came from and shows it as that variation's source. If a remix also borrows from other variations, ask the agent to say so in its commit message, such as “Remix the sun planner with who booked what”. Groups can keep growing this way; you don't need to prune them before comparing.

## Browse the group

Open your original project's Critter viewer and select the version name in the top bar to open the history. The group appears as one row under its name, **Rooftop sun**, with a line such as **3 variations · Sun planner · Building view · Shared planner** listing the variations in the order they were made. Select the row to open the variation that changed most recently.

![Critter's history showing Rooftop sun as one row of four variations, below the bar's switcher with the group's name, a tab for each variation and the count 4 of 4.](/images/solar-commons-variation-group.webp)

While a variation is on screen, the bar becomes the group's switcher: the group's name, then a tab for each variation, then a count such as **2 of 3** between two arrows. Select a tab, use the arrows, or press **[** and **]** to flick between variations at the same route and scroll position. **←** and **→** still step through one variation's own commits. When a group has more variations than fit, the tabs scroll sideways and the ones beyond the edge peek in. Select the group's name to reopen the history.

Historical versions are prepared when you select them. HTML uses committed files directly; framework builds may take longer on the first opening than a cached version.

## Compare two directions

Select **Compare** in the bar. For a remix, Critter puts it beside its source; otherwise it puts the variation beside the next one in the group. You can also choose **Compare** on another row in the history.

When a pane shows a variation, its header shows the group's name and the same switcher, so you can change that side to another variation without leaving the comparison. When both sides come from one group, the variation on the other side is dimmed in each switcher, so you can't put the same design on both sides. Select the tab on screen in either header to choose any other version for that side, such as an ordinary commit or the live app.

## Choose by using the interfaces

Review both at the same route and size. Look for the consequences of each choice: does the planner make it clear when to book, does the building view make spare power easier to see, and what becomes harder to reach?

Use highlights to locate changes, then hide them to judge the complete design. An element that exists on only one side is marked as added or removed. Try the actual disclosures and controls. Synchronization is useful for matching interactions, but you can turn it off when the layouts behave differently.

The [Solar Commons walkthrough](/guides/recover-a-dropped-feature/) shows how larger visual changes make these decisions visible. The [comparison guide](/guides/compare-ui-commits/) covers the viewer controls in more detail.

## Continue with the selected direction

After choosing a direction, return to the original project directory and review its working-tree status. `explore use` requires a clean working tree:

```bash
git status --short
critter explore use rooftop-sun/building-view
git diff
```

This applies the direction's changes from its shared base without moving `HEAD`. It is not a branch checkout or an automatic merge decision. Review the applied diff, run the project's checks, refine it if needed, then stage and commit the intended result normally.

The alternatives remain useful reference points, and the group keeps them together in the history, so there's no need to bookmark them. Keep their branches and worktrees until you no longer need them, then clean them up through your normal Git workflow.

If a design was committed without its own branch, `critter explore add rooftop-sun/sketch` registers the current `HEAD` under that name instead. It records the commit only, not uncommitted edits.

Historical previews contain static files, so they do not restore earlier backend data or external-service state. Use consistent fixtures when those differences would distract from the design question. Critter's role is to keep interface choices available for review while you and your agent develop them.

---

Canonical page: https://critter.sh/guides/explore-design-variations/