Skip to main content

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.

Updated
Reviewed

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: the lifecycle status mark, row status signals, badge salience, the quick state filter, collapsed states, and per-card recovery.
  • Worktrees Overview: the large dialog 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 previously registered repository whose .git is now proven absent opens the explicit non-Git choice again before giving up Git capabilities. An unreadable mount or transient probe failure does not silently downgrade it.

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.

That row still carries the actions that make sense for a plain folder. A Browse files button opens the file browser at the workspace root, and the More actions menu (the same items on right-click) launches agents and panels, opens the folder in your editor or file manager, copies the root's path or its context, and runs project-wide recipes. Review, sessions and delete are left out because they need a worktree.

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.

Note
A folder initialized as a repository from outside Daintree is picked up on the next open: the live probe wins over the stored flag, so you do not have to re-add the project. For the workspace model itself, see Projects.

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 can't be deleted. Every other worktree can be, including one that lives outside the project directory, so read the delete preview before you confirm. For the ordinary case, four stages:

  1. Create one from a new branch, an existing branch, or a pull request. Several at once from a set of issues.
  2. Work in it. Agents you launch while it is selected start in its directory on its branch. Its card carries the status.
  3. Review and ship what changed, scoped to that worktree alone.
  4. 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. To run the whole project, its worktrees and its agents on another Mac or Linux machine instead, see Remote Hosts. Once you have added a host, the New Worktree dialog gains a Host row for creating the worktree on another machine.

Moving an Agent Between Worktrees

Two actions move a panel out of the worktree it started in. Both sit on the panel's right-click menu and its three-dot menu. Either way the panel is refiled under the other worktree in place: the process inside it keeps running and nothing restarts.

  • Move to worktree: on the right-click menu, a submenu of up to ten other worktrees, ending in More worktrees… when the project has more. The three-dot menu's Move to worktree… opens a searchable picker of all of them.
  • Move to new worktree…: opens the standard New Worktree dialog and, once the worktree is created, moves the panel into it. It is offered only for panels launched as an agent; plain shells, browser panels and dev-preview panels don't get it.

Moving a panel does not change the directory its process works in. An agent started in the old worktree keeps editing files there until it is told otherwise, so after you move a live agent its pane shows a one-line notice: Agent may still be in the old worktree. Tell it to continue here sends the agent Please continue in the directory <new worktree path>, after anything already typed in its input bar. The close button dismisses the notice and sends nothing. If the text doesn't reach the terminal, the notice turns red and offers Retry.

Plain shells get no notice, since typing a sentence at a shell prompt would only produce an error. A panel whose process has already exited needs none either: its next restart launches in the new worktree. Moving a panel back to the worktree it started in clears the notice.

Note
A new worktree starts without node_modules and other untracked files. Small gitignored files such as .env can be copied in automatically with a .worktreeinclude file, and dependency installs can be automated 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:

ActionShortcut
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 Option-Command-R Control-Alt-R Control-Alt-R
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-Shift-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 Compare worktrees dialog shows how their branches diverge. Open it by right-clicking a card and choosing Review > Compare with another worktree… (the clicked worktree pre-fills the base side), from the three-dot menu, or from the action palette with nothing pre-selected.

Two pickers sit at the top: Base and Compare, with the main worktree first (marked (main worktree)) and the rest alphabetical. Each disables whatever the other has selected. A worktree on a detached HEAD is listed but can't be picked, because there is no branch to compare. The comparison runs as soon as both sides are set.

A file list on the left, headed by a summary of the whole change set, groups every changed file under its directory. Each file carries a single-letter status badge and its per-file churn:

BadgeMeaning
AAdded: exists only in the compare branch
DDeleted: exists only in the base branch
MModified between the two branches
RRenamed or moved
CCopied from another path

Clicking a file loads a split diff with syntax highlighting on the right; [ and ] step to the previous and next file. Long lines wrap by default in prose files and not in code; the Wrap long lines button in the diff toolbar overrides that, and the choice is shared with the other diff views. Binary files and diffs over 1 MB show a placeholder. The per-file diff honors the global ignore whitespace preference.

Tip
To see what another agent added, put your worktree (or main) in Base and the agent's branch in Compare: anything that exists only in the compare branch shows as green lines.

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.

Compare the two branch tips, then step through their files

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 has two arm controls. The small lightning button at the trailing edge of the quick state filter bar arms every agent the current filter shows, covered on Worktree Cards. Select terminals to arm, among the sidebar header's buttons, opens the fleet picker for choosing terminals one by one. 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.