Design iteration with a coding agent

Critter gives you a browser view of the interfaces your agent builds. The agent makes changes and handles Git; you try the results, compare versions, and choose what to keep.

Install Critter, then have your agent read the guidance included with the installed version:

critter skills get core

The command prints the workflow. Critter does not launch coding agents or automatically create designs, branches, or worktrees.

Start with ordinary iteration#

For a sequence of refinements, use the normal development loop:

1. Give the agent a concrete interface goal.
2. Let it implement a focused change.
3. Review the live result through Critter.
4. Refine it with your feedback.
5. Commit a useful step when it is ready and committing is part of the agreed workflow.
6. Use Critter's history and comparison controls to revisit the result.

For a Vite or statically exportable Next.js app, run critter view in place of the usual development command. For a plain HTML prototype, point at the page:

critter view prototypes/today.html

Use the existing project as it is. An HTML prototype does not need a new framework or build pipeline to work with Critter.

Normal commits appear in the viewer without separate registration. Their subjects become version labels, so describe the visible change: “Add a Book button to free washers” is more useful to review than “Update styles.”

Critter does not require a commit for every edit. The live version remains available while you work.

Bookmark versions worth keeping#

A commit subject describes what changed. A bookmark marks a version you want to come back to, with your reason: “Book buttons work here.”

Bookmarks are yours. In the viewer, 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 are keeping it. The reason appears under the version's title; select it to edit it in place. Select the tinted bookmark to remove it; Undo is offered for a few seconds. Only show bookmarks at the top of the history filters the list, and when you choose a side to compare, bookmarked versions are listed first. Variations aren't bookmarked; their group already keeps them together.

Your agent adds a bookmark only when you ask, such as “bookmark this as the calm navigation”, and writes your reason in your words. It can also find a version from your description of its bookmark: “compare the live app with the one I bookmarked as the calm navigation.”

Bookmarks are Git notes in refs/notes/critter. The note text is the reason, and an empty note is a bookmark without one. Adding or editing a bookmark does not amend the commit. Notes have their own history and are not pushed with a code branch, so share them explicitly when collaborators should see them:

git push origin refs/notes/critter

Compare the same screen#

For a framework app, start on the route you want to review:

critter view --route /bookings/laundry

If the viewer is already running, update its route:

critter route /bookings/laundry

Use a route that exists in your app. For HTML, passing the file to critter view pins that page automatically; no extensionless app route is needed. To select another HTML page, run critter view with its file path.

Select Compare in the bar, or on a version in the history, then inspect the two interfaces with change highlights and synchronized interactions. Use a specific review question: Is the information easier to scan? Is the main action clearer? Does this layout work at a narrow width? The highlights show changes; you decide whether they help.

Use alternatives when the ideas differ#

When you want several distinct answers to one design question, ask your agent to develop each on its own branch, usually in its own worktree. The agent sets up that Git workflow using the included guidance. The branch name, critter/<question>/<variation>, is the registration:

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

Critter groups both branches as one Rooftop sun row in the history. Open it, and the bar becomes the group's switcher: flick between the variations with its tabs, its arrows, or [ and ]. Compare puts two variations side by side, and each pane's header keeps the switcher so you can change either side. A variation branched from another is a remix, and Critter compares it with its source first.

After you choose, return to the working tree where you want the result, ensure it is clean, and apply the selected alternative:

critter explore use rooftop-sun/sun-planner

This applies the alternative's changes from its shared base without moving HEAD. Review the applied changes and commit normally when ready. Resolve existing work first; do not discard it simply to make the working tree clean.

The design variations guide walks through this process. Use troubleshooting if a preview or application step fails.