critter

a CLI for your agent — runs a structured design loop

a viewer for you — flick through and compare iterations

For people refining UI with Claude Code, Codex, Cursor, or another coding agent. The CLI gives the agent commands for kickoff interviews, checkpoints, divergent variants, and critique prompts. The viewer gives you a visual history of every iteration so you can flick through and compare side-by-side.

critter is designed for your agent to run inside your harness of choice — you don't run the commands yourself.

Early Access

This is very early release software. You probably do not want to install it unless you are explicitly testing it with me, or you are comfortable with rough edges in a tool that asks an agent to make git commits in your repo.

Install

npm i -g @idamadam/critter

Then open a git repo in your coding agent and say:

run critter in bash

The agent runs:

critter

That prints the command index. Agents should then read the full loop protocol:

critter protocol

Commands

critter                          # help / command index
critter protocol                 # top-level protocol for agents
critter kickoff                  # interview protocol for a fresh loop
critter brief                    # print the current design brief
critter checkpoint "<message>"   # git commit + record checkpoint
critter diverge                  # protocol for scratch variant exploration
critter apply <group>/<variant>  # apply a variant into the working tree
critter eval before-after        # pairwise critique prompt
critter eval variation           # N-way variant critique prompt
critter view                     # launch the visual history viewer
critter browser <subcommand>     # passthrough to agent-browser
critter doctor                   # check setup for early-test debugging

Basic Loop

Start by asking the agent to run:

critter kickoff

This prints an interview protocol. The agent asks about intent, taste, constraints, references, dealbreakers, and criteria, then writes the result to .critter/brief.md.

When a design state feels worth saving, say something natural like:

"this is feeling good, let's commit"

The agent runs:

critter checkpoint "tightened filter pills, upright card weight"

That stages and commits the current project changes, then marks the commit as a critter checkpoint.

To explore options, the agent runs:

critter diverge

That prints a protocol for creating scratch variants. Variants are saved on Critter's internal git refs, not on your active branch. When you choose one:

critter apply hero-explore/minimal

This applies the variant diff into the current working tree without committing, so the agent can blend, edit, and checkpoint the result.

Visual History

critter view

Launches a local viewer for browsing checkpoints as interactive snapshots of the app. Historical checkpoints are built into static exports cached under .critter/builds/<sha>/.

First build of a checkpoint can take a minute or two. After that it is cached. If the cache gets large, delete it:

rm -rf .critter/builds/

The viewer currently supports projects with Next.js or Vite.

Browser Access

critter bundles agent-browser, so the agent can look at the current UI or reference sites instead of asking you to describe them.

critter browser open http://localhost:3000
critter browser screenshot current.png
critter browser snapshot

Every agent-browser subcommand is available through critter browser.

Doctor

critter doctor

Checks the local repo, git identity, package manager, viewer framework, .critter/builds/ ignore rule, and bundled browser dependency. It does not send telemetry or change project files.

For the full browser launch and network diagnostic:

critter browser doctor

Boundaries

• No telemetry.
• No API keys.
• No inference inside the binary.
• No source edits from critter view; snapshot builds happen in throwaway git worktrees.
• critter checkpoint creates git commits. Other workflow commands mostly print protocols or apply explicit candidate diffs.
• .critter/builds/ is a local cache and should be gitignored.

Why This Exists

The core idea is simple: the CLI prints prose instructions that an agent can read and follow at the moment they are needed.

Most agent tooling is either structured tool output (MCP, JSON CLIs) or static instruction files (skills, rules, AGENTS.md). critter uses a third shape: the binary ships the protocol, and npm update -g @idamadam/critter updates the loop.

That is useful here because the important parts of the workflow are prose-shaped: how to run a taste interview, what makes a checkpoint message useful, when to diverge, how to compare variants, and when to treat "nice, ship it" as a convergence signal.

Status

v0.1. Early and intentionally small.

If you are one of the first testers and something breaks, run:

critter doctor
critter browser doctor

Then send the command you ran, the output, your OS, Node version, package manager, and project framework.