Worktrees as iterations

iterate packages git worktrees into an easily navigable toolbar system, allowing you to ideate in parallel easily.

How it works

Each iteration is a full git worktree with its own branch, dev server, and port. The toolbar loads each server in an iframe and layers an interactive overlay on top for selecting elements, adding annotations, and dragging components. When you submit feedback, Claude Code edits the source files directly and the dev server hot-reloads.

From the toolbar:

The fastest way to create and manage iterations is through the toolbar overlay.

1. Create iterations

Click Fork in the toolbar to create 3 iteration worktrees. Each gets its own branch, dev server, and port. Tabs appear so you can switch between them.

2. Review and refine

Switch between iteration tabs to compare. Select elements, describe what you want changed, drag things around. Each change is scoped to the active iteration tab. When you're ready to implement changes, run the slash command:

/iterate:go

The agent reads all pending changes, modifies the code, and the dev server hot-reloads. You see results immediately. Rinse and repeat endlessly.

3. Pick a direction

Once you favor a direction, click Pick in the toolbar or run the /iterate:keep <tab/worktree-name> command. The desired branch merges back to the base branch and all other worktrees and branches are removed. You're left with a single codebase.

/iterate:keep hero-v2

The Discard button does the opposite — it keeps the original and removes all iteration worktrees. Both Pick and Discard clean up worktrees regardless of where they live (see auto-discovery below).

From the command line:

You can also manage iterations through slash commands in your Claude Code session:

• /iterate:prompt — create multiple iteration worktrees from a verbal prompt, if you have an initial concept you want to riff on
• /iterate:go — implement all pending changes from the toolbar overlay
• /iterate:keep — choose a preferred iteration to merge back to the base branch and clean up the rest

Improving on worktree management

Claude Code already supports git worktrees, but they only contain committed files. If you have uncommitted edits, untracked components, or gitignored config like .env.local, a vanilla worktree starts from a blank slate. iterate fixes this by automatically copying your full working state into every new worktree — so each iteration begins exactly where you left off.

This is a fundamental step-change: without it, every worktree needs manual setup — re-applying patches, recreating config files, re-installing dependencies with the right environment. With iterate, you fork your exact working state and start jamming immediately.

Auto-discovery

iterate automatically discovers worktrees in two locations:

• .iterate/worktrees/ — the default location where iterate creates worktrees. These appear as tabs automatically when the daemon starts.
• .claude/worktrees/ — the standard location when worktrees are enabled in a Claude Code session. Any git worktree here with a running dev server is detected and shown as a tab.

The Pick and Discard toolbar buttons work across both locations — merging or removing all discovered iteration worktrees regardless of where they were created.

Copying uncommitted files into worktrees

Git worktrees only contain committed files from the current branch. To ensure each iteration starts with the same working state as your current checkout, iterate automatically copies two categories of files from the project root into every new worktree:

1. Uncommitted changes

All modified, staged, and untracked files detected by git status are copied into each new worktree automatically. This means your in-progress work (edited source files, new components, updated configs) is available in every iteration from the start. Deleted files are also reflected in the worktree.

2. Config files (copyFiles)

Some files like .env.local are gitignored and won't appear in git status, but dev servers still depend on them. The copyFiles config option handles these by copying matching files from your project root into each new worktree. By default it copies all .env* files:

{
  "copyFiles": [".env*"]
}

You can add additional glob patterns for other untracked files your dev server needs:

{
  "copyFiles": [".env*", "credentials/**", "*.local"]
}

Example session

1. Run /iterate:prompt "Create 3 distinct hero sections" or press the Fork button on the toolbar.
2. Switch between tabs in the toolbar to compare.
3. Select elements, annotate what you'd change, drag things around.
4. Implement all changes by simply typing /iterate:go in your Claude session.
5. The agent reads all pending changes, implements them, and the dev server hot-reloads.
6. Satisfied with an iteration? Press Pick in the toolbar or enter /iterate:keep <tab-name> in your chat session.
7. The preferred branch is merged to base and other worktrees are removed. Or use Discard in the Original tab to delete all worktrees and keep the base changes.