Git Worktrees

  • Desktop app
  • All plans
View as Markdown

What it does

A worktree is a separate checkout of your repository on its own branch, inside the project under .worktrees/<branch>/. Giving an agent or a backlog ticket a worktree lets several agents work on the same repository at once without sharing files: each one edits, builds and commits in its own folder. A ticket can auto-merge its branch into the current branch when it is marked done. A saved agent template or a default profile can ask for a fresh worktree on every spawn, so agents born from the same template never collide. Before an agent's first launch in a new worktree, AgentsRoom prepares it: the git-ignored files the project needs (.env files by default) are copied from the main checkout and the dependencies are installed (yarn install, pnpm install, uv sync... detected from the lockfile), so the agent can build and run the tests right away.

Where to find it

  • Backlog ticket form, Execution zone: Code in a separated worktree for this task, then the Worktree picker (the project's existing worktrees as chips, New branch to type a Branch name) and Auto-merge into current branch when task is done.
  • Add Agent modal: the Workspace card, always visible next to Provider / Model / Reasoning (it used to be folded inside Advanced options); a click opens the Worktree selector (Main, an existing worktree, or New to create one). Edit Agent modal: the same selector, above Advanced options.
  • Agent templates and the Quick Agent / Backlog Agent default profiles: New worktree per agent.
  • Project settings > Defaults, Git: Worktree base branch (default: the remote default branch) and Prepare new worktrees (install command, files copied from this checkout).
  • There is no sidebar button or dedicated panel: worktrees are reached from the backlog ticket form and the agent modals. The Worktree selector lists the existing ones.

How to use it

  1. Create or edit a ticket, tick Code in a separated worktree for this task. Under Worktree, click one of the project's existing worktrees (including one you created by hand with git worktree add), or click New branch and type a Branch name: it is pre-filled from the title until you edit it, and a name you chose is kept as is when the ticket is reopened. Optionally tick Auto-merge into current branch when task is done.
  2. Start the ticket (drag to In Progress or Start task). AgentsRoom fetches the base branch, creates the worktree (or reuses the one you picked) and starts the agent inside it.
  3. When you mark the ticket Done, the branch is merged into the current branch if auto-merge is on; the confirmation shows the merge result. The worktree itself is kept for review.

Clicking a file path printed in the console of a worktree agent opens the file from that agent's checkout, not the stale copy of the same name in the main checkout; this also holds for a path tapped on the phone.

The first time an agent starts in a new worktree, its terminal shows the install command ($ yarn install) and its output, then the agent CLI starts; a toast "Preparing the worktree" says what runs and how many ignored files were copied. This happens once per worktree: the next launches start the agent directly. A failed install does not block the agent: the error stays in the terminal and the agent can fix it.

For an ad-hoc agent, pick or create a worktree in the Worktree selector of the Add Agent modal. For a whole family of agents, turn on New worktree per agent on a template or a default profile: each spawn gets a branch named agents/<template or role> (-2, -3 for the next free name).

Settings

  • backlogAutoCommitOnDone (global, Settings > Backlog > Commit automatically when work is done; project override): commits everything the ticket's worktree holds when it is marked done, before the auto-merge. Without it, the merge only carries what the agent committed itself. See Backlog Task Board.
  • worktreeBaseBranch (project, Project settings > Defaults > Worktree base branch): the branch every new worktree is cut from, fetched first so a task starts from up-to-date code. Absent = the remote default branch.
  • worktreeSetupEnabled (project, Project settings > Defaults > Git > Prepare new worktrees): prepare every new worktree before its first agent. Absent = on; false leaves new worktrees untouched.
  • worktreeSetupCommand (project, same row, Install command): the command run in a new worktree before the agent starts, for example pnpm install && pnpm build:deps. Absent = detected from the lockfile at the root: bun install, pnpm install, yarn install, npm install, uv sync, poetry install, pipenv install, bundle install, composer install; nothing runs when there is no lockfile. The placeholder of the field shows the detected command.
  • worktreeCopyFiles (project, same row, Files copied from this checkout): git-ignored files copied from the main checkout into a new worktree, one pattern per line relative to the project root (.env*, apps/web/.env.local, config/*.local.json; a **/ prefix also searches subfolders, files only). Absent = **/.env*; an empty list copies nothing. A file already present in the worktree is never overwritten, and node_modules, .git, .venv, dist, build are never searched.

Agent tools (MCP)

  • backlog_create, backlog_update: accept useWorktree, worktreeBranch and autoMergeWorktree on a ticket; an omitted field keeps its stored value.
  • backlog_get, backlog_list: return those fields.
  • backlog_start_next: starts the next ticket in its worktree and reports the checkout's base (ref, commits behind, whether an existing checkout was reused) when it is not a clean cut.

Providers

All providers: the worktree is the agent's working directory whatever CLI runs. Kimi Code and Antigravity trust a folder by its exact path, so a new worktree used to stop them on their "trust this folder" question; since 2026-09-26 AgentsRoom records the worktree as trusted for them before the launch (see Multi-Provider Support).

Mobile

An agent started from the phone in a new worktree gets the same preparation (install and .env copy), with the project's own settings: the desktop runs it at the launch, whatever device asked for it.

The ticket form of the mobile companion has no worktree field: a worktree is asked for from the desktop, or by the Backlog Agent profile. A ticket that already asks for one and is started from the phone now runs in its worktree (since 2026-09-22), through the same checks as the desktop: when the worktree cannot be created the ticket is not started, stays where it was, and the phone shows the reason instead of quietly falling back to the project root. A phone that has not been updated does not send those two fields, so such a ticket still starts at the project root.

Limits

  • The preparation runs once per worktree, at the first agent launch in it. To run it again, remove the worktree and create it again, or run the command yourself in the agent's terminal. Worktrees created before 2026-09-28 are prepared at their next agent launch.
  • The install command runs in your usual shell (zsh, bash, PowerShell): write it in that shell's syntax. On Windows PowerShell 5.1, && does not exist; use ; or a script.
  • The preparation is skipped for a project opened on an SSH server or whose agents run on a remote host: the worktree lives on the host, prepare it there.
  • Each Own checkout step of a team run is a new worktree, so it is prepared too (install included) at its first launch.
  • Requires a git repository at the project root. A project opened on a folder that only groups several repositories side by side gets no ticket worktree, and since 2026-09-29 the Changes tab says so up front ("This folder is not a git repository." followed by what needs one: auto-commit on done, one worktree per ticket, team step diffs). Open each repository as its own project.
  • If the worktree cannot be created (no repository, locked index, invalid branch name), a template or profile agent is still created at the project root; a ticket that explicitly asks for a worktree is not started and a toast names the branch and git's reason ("Could not open the git worktree for branch ..."). A ticket that names an existing worktree by its folder or path, rather than its branch, is still matched to that worktree.
  • A worktree is never deleted automatically; the folders accumulate under .worktrees/ and are removed by hand (git worktree remove). Removing a worktree while an agent runs inside it breaks that agent's terminal.
  • Auto-merge that hits conflicts logs a warning and the ticket still moves to done; resolve the merge by hand.
  • Re-starting a ticket reuses its existing worktree and branch. A branch that already existed with its own commits is flagged "could not be brought up to date" rather than silently served as fresh.
  • A QA agent never gets its own worktree: it tests inside its master agent's checkout, because a fresh worktree would not contain the uncommitted work under test.
  • Team runs started by a trigger use the project root.
  • A project opened on an SSH server gets its ticket worktrees since 2026-09-22: the checkout is cut on the host, under .worktrees/ of the remote checkout, and the agent starts in it. Exception: a desktop that reaches the host over a password-authenticated connection with no open terminal tab has no way to run git there, so the ticket is refused rather than started. A step's Own checkout in a team run is still refused on such a project, and the run stops with the reason.
  • A project with a local checkout whose agents are offloaded to an SSH host cannot use worktrees: the checkout would be cut here, where the agent never looks. The ticket is not started and says so ("Git worktrees are not available when a local checkout runs its agents on a remote SSH host ... untick "Code in a separate worktree" on the ticket, open the project directly on the server, or run it locally").
  • A team run on a worktree ticket keeps its run state at the project root, so a final step that removes the ticket's worktree (git worktree remove) no longer prevents the run from finishing. Runs started before this change keep their state in the worktree until they end.
  • A path clicked on the phone is only found in a worktree that lives inside the project folder.

Common questions

  • An agent in a worktree has no dependencies and cannot run the tests. Fixed on 2026-09-28: a new worktree is prepared before its first agent (dependencies installed, .env files copied). If your project needs more than the detected command, set it in Project settings > Defaults > Git > Prepare new worktrees > Install command.
  • My agent in a worktree is missing its .env. The default copies every .env* file of the main checkout. A secret file with another name goes in Files copied from this checkout.
  • Where is the worktree option? I only saw it in Advanced options. It moved: the Add Agent modal now shows a Workspace card under the agent, always visible.
  • Why did two agents overwrite each other's files? They shared the project root. Give each ticket a worktree, or turn on New worktree per agent on the profile they spawn from.
  • Which commit is a new worktree based on? The Worktree base branch (remote default by default), fetched right before branching; the ticket form says which branch it will branch from.
  • The auto-merge brought nothing back? The merge only carries commits: the agent left its work uncommitted. Turn on Commit automatically when work is done (Settings > Backlog) so the worktree is committed before the merge.
  • Is the worktree removed when the ticket is done? No, on purpose, so you can review it. Remove it by hand when you are finished.
  • Can I see the worktrees in the sidebar? No. Reach them from the backlog ticket form or the Worktree selector of the agent modals (the Workspace card of the Add Agent modal).
  • I created a worktree by hand and the ticket said "not a valid branch name". The old form was a free text field expecting a branch, and a folder name typed there was refused. Pick the worktree from the chips of the ticket form instead; a folder or path still typed by hand is matched to the existing worktree.
  • The branch name I typed on a ticket was replaced by a slug of the title. Fixed: reopening a ticket no longer re-derives the branch from the title once a name is stored on it.
  • Clicking a file in a worktree agent's console said "file not found", or opened an old version. Fixed: the file is now looked up in the agent's own worktree first, then in the project.
  • My agent in a worktree had no AgentsRoom tools at all: no backlog, no memory, no embedded browser. Fixed on 2026-09-22 for Claude Code and Copilot, the two CLIs that read the tool declaration of the folder they start in: an agent started outside the project root now receives the AgentsRoom servers with its launch options instead of finding nothing. The other CLIs were already covered.
  • My ticket asks for a worktree and my project runs its agents on a server. It depends which kind of remote project. A project opened on the server gets its worktree there and the agent starts in it. A local checkout merely offloaded to a host refuses the ticket and tells you to open the project on the server instead, because a worktree cut on this computer would be invisible to the agent.
  • I started a worktree ticket from my phone and the agent worked in the shared checkout. Fixed on 2026-09-22: the phone now sends the ticket's worktree and branch, and the desktop resolves them with the same code as a start from the board.

Related