Worktrees
How Daintree creates, navigates, compares and deletes Git worktrees, what happens to agents when a worktree is deleted, and what a workspace without a repository does instead.
Worktrees
Daintree runs several agents against one repository at once by giving each its own Git worktree. A worktree has its own branch and its own working directory, so two agents can edit the same project without touching each other's files.
This page covers the shape of the thing: what a worktree is, what it needs, how you move between them and compare them. Each stage of the lifecycle has its own page:
- Worktree Cards: the anatomy of a card in the sidebar: lifecycle chips, row status signals, badge salience, the quick state filter, collapsed states, and per-card recovery.
- Worktrees Overview: the full-bleed modal for multi-select and bulk actions across every worktree in the project.
- Remote Compute: per-worktree resource environments that provision and tear down external compute alongside the worktree.
Worktrees Need a Repository
A Daintree project no longer has to be a Git repository. Any folder opens as a workspace, and worktrees are the part of the model that a repository buys you. Daintree probes the folder on open rather than trusting a stored flag, so a repository whose .git was deleted behaves the same as a folder that never had one.
In a workspace with no repository, the sidebar shows a single row for the workspace root, headed Workspace rather than Worktrees. Everything worktree-shaped is absent rather than disabled: no create-worktree button, no overview, no refresh, no search bar or quick state filter over a one-row list, and no fleet-arm control. There is exactly one place agents run, so there is exactly one row.
A footer button, Initialize repository, opens the git-init dialog and upgrades the folder in place. Below it sits the reason you might not: Terminals, agents, and recipes work without one. Scratch workspaces are app-managed and disposable, so they are never offered the upgrade.
The lifecycle
A task worktree usually exists for one piece of work and goes away when that work merges. The project's main worktree is not one of these: it is protected, and so are any long-lived or external worktrees you keep around. For the ordinary case, four stages:
- Create one from a new branch, an existing branch, or a pull request. Several at once from a set of issues.
- Work in it. Agents you launch while it is selected start in its directory on its branch. Its card carries the status.
- Review and ship what changed, scoped to that worktree alone.
- Delete it. If you deleted the wrong one, the agent sessions can be rescued. The directory and anything uncommitted in it cannot.
Worktrees Overview is where you triage a lot of them at once: search, multi-select, close sessions in bulk, remove in bulk. Remote Compute attaches a worktree to a provisioned remote environment, which agents reach through an explicit wrapper once it is configured.
Moving an Agent Between Worktrees
Two actions move a running agent panel out of the worktree it started in. Both sit on the panel's right-click menu and its three-dot menu.
- Move to worktree: a submenu of every other worktree in the project. The panel changes its worktree association in place; nothing restarts.
- Move to new worktree…: creates a worktree and transfers the session into it.
The gate on Move to new worktree… is simply that the panel was launched as an agent. Every registered agent qualifies. Plain shells, browser panels and dev-preview panels do not.
What Move to new worktree… does:
- Captures the terminal's visible output buffer, up to 20,000 characters, with escape sequences stripped. This happens before any teardown, while the renderer is still alive.
- Opens the standard New Worktree dialog. Choose a base branch and a name as usual.
- On confirm, the panel's working directory and worktree association update and the agent restarts in the new directory.
- Once the agent goes idle, the captured history is injected as an opening prompt.
The transferred history is terminal output, not structured session data. It is a best-effort handoff: enough context to continue, but not full recall of earlier reasoning. An empty buffer (a panel just launched or just restarted) injects nothing and the agent starts fresh.
The new worktree also starts without node_modules and other untracked files. Re-run setup by hand or automate it with lifecycle scripts.
Moving the last surviving terminal off a deleted-worktree row is a rescue, so the move follows: Daintree selects the destination worktree rather than snapping back to main and stranding the session off-screen.
Switching Worktrees
Click a card in the sidebar, or use the keyboard:
| Action | Shortcut |
|---|---|
| Switch to worktree 1–9 | Option-Command-1, through Option-Command-9 Control-Alt-1, through Control-Alt-9 Control-Alt-1, through Control-Alt-9 |
| Switch to next worktree | Option-Command-] Control-Alt-] Control-Alt-] |
| Switch to previous worktree | Option-Command-[ Control-Alt-[ Control-Alt-[ |
| Open the worktree palette | Command-K, then Command-O Control-K, then Control-O Control-K, then Control-O |
| Create a new worktree | Command-K, then Command-N Control-K, then Control-N Control-K, then Control-N |
| Toggle the worktrees overview | Shift-Command-O Control-Shift-O Control-Shift-O |
| Open changes for the focused worktree | Shift-Command-D Control-Shift-D Control-Shift-D |
| Open the file browser for the focused worktree | Option-Command-F Control-Alt-F Control-Alt-F |
| Copy tree context for the active worktree | Shift-Command-C Control-Shift-C Control-Shift-C |
Switching a worktree swaps the panel grid to that worktree's terminals and re-tiers rendering. Terminals run at four refresh tiers: 60 FPS in a burst while you type, 10 FPS focused, 5 FPS visible, and 1 FPS in a background worktree.
Comparing Worktrees
When several agents work in parallel, the cross-worktree diff shows how their branches diverge. Open it by right-clicking a card and choosing Compare Worktrees… (the clicked worktree pre-fills the left side), from the three-dot menu, or from the action palette with nothing pre-selected.
Two pickers sit at the top: Left (base) and Right (compare), with the main worktree first and the rest alphabetical. Each disables whatever the other has selected. The comparison runs as soon as both sides are set.
A file list on the left shows every changed file with a single-letter status badge and its per-file churn:
| Badge | Meaning |
|---|---|
| A | Added: exists only in the right worktree |
| D | Deleted: exists only in the left worktree |
| M | Modified between the two branches |
| R | Renamed or moved |
| C | Copied from another path |
Clicking a file loads a split diff with syntax highlighting on the right. Binary files and files over 1 MB show a placeholder. The per-file diff honors the global ignore whitespace preference.
This modal compares branch tips, not merge bases, so it shows the full difference between two snapshots regardless of shared history. Uncommitted changes are not included. For staging, committing and pushing within one worktree (and for the merge-base view of a branch against its base), see Review Hub and the diff workspace.
Fleet Arming
Fleet arming acts on several agent terminals at once. You arm a set, and every Accept, Reject, Interrupt, Restart, Kill or Trash (plus anything you broadcast) fans out to all of them. The armed set holds until you disarm it.
The sidebar's own arm control is the small lightning button at the trailing edge of the quick state filter bar, covered on Worktree Cards. The full reference (the arming ribbon, keystroke mirroring, per-target variable resolution, broadcast gates, the Fleet Deck, saved fleets and the shortcut table) lives at Fleet. For a cross-project view of every agent run rather than one project's worktrees, see Pilot.