Git Worktrees
- Desktop app
- All plans
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.
Video (1 min 25 s): Git Worktrees, shown in the real app. A first agent adds a footer in the main folder of a small shop project, a task ticked Code in a separated worktree for this task starts a second agent in its own copy after npm install and the .env copy, the Worktree selector of the Changes tab shows each copy apart, and Done merges the task's branch into the project.
Where to find it
- Backlog ticket form (New Task on the board), Execution zone, under Advanced options (below Provider / Model / Reasoning): 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. Picking such a saved agent in the Add Agent modal shows it on the Workspace card and pre-selects its branch (
agents/<name>) in the Worktree selector. - Project settings > Defaults, Git: Worktree base branch (default: the remote default branch), Prepare new worktrees (install command, files copied from this checkout) and Remove finished worktrees (off by default).
- Add / Edit Agent modal, New in the Worktree selector: a From menu under the branch name shows the branch the new worktree is cut from (Project default (origin/main)) and lets you pick another branch for that worktree only.
- Right panel, Changes tab: the Worktree selector at the top (Main plus each worktree with its branch) picks which checkout the diff, Commit, Pull and Push act on. In the branch switcher, a branch checked out in another worktree shows that worktree's name and Open this worktree.
- Right panel, Changes tab, third segment Worktrees (next to Working tree and History): every checkout of the repository in one list, with its diff, Merge, Open a pull request, Delete worktree... and Clean up.
- In an agent's conversation view, under each answer: N files changed in this turn.
- Worktrees are created from the backlog ticket form and the agent modals; they are deleted from the Worktrees view (or by hand).
How to use it
- 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. - Start the ticket (drag to Development, Start on the card, or Start task). A toast "Preparing the worktree" says which install runs and how many git-ignored files were copied; the agent's terminal shows the install output, then the agent starts in
.worktrees/<branch>/. The agent also receives a note telling it to commit its finished work on the branch, because only committed work is merged. AgentsRoom fetches the base branch, creates the worktree (or reuses the one you picked) and starts the agent inside it. - When you mark the ticket Done (the Done button in the header of the task's agent, or the board), the branch is merged into the current branch if auto-merge is on; the confirmation shows the merge result ("Task Completed", "Merged <branch> into current branch", then a toast "Automatic merge") and the task's agent closes. 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.
To review, commit or push the work of a worktree, open the Changes tab and pick it in the Worktree selector (it appears as soon as the repository has a linked worktree). The file list, the diffs, the review, Commit, Pull and Push then run in that worktree; pick Main to come back. Clicking the pill of an agent that works in its own worktree also shows that worktree. In the branch switcher, a branch that another worktree holds cannot be checked out here (git refuses it), so its row opens that worktree instead; if git refuses a switch for that reason anyway, the error offers Open this worktree.
To see every checkout at once, open Changes > Worktrees. Each row is one checkout (Main and each worktree, the most recently active first): its folder and branch, the agents working there with their live status dot, the uncommitted files and lines (+/-), the commits ahead and behind the base branch, the last activity, the ticket and the CI badge once the branch is pushed. Click a row to open its diff: the Compare picker offers Uncommitted changes, Whole branch since its base (committed plus uncommitted work against the merge-base with the base branch, what a pull request will contain), each commit of the branch, each recorded agent turn, and Compare with any other branch. The file list shows the changed files as a Tree by folder or a Flat list (the toggle icon in the diff header, the same choice as in the Changes tab), and its edge can be dragged to widen it so long paths stay readable. Click a file to read the whole file with the changes highlighted in place, word by word on modified lines; Collapse unchanged folds the long unchanged runs and each fold opens with a click. Open in a tab puts that diff in a workspace tab next to the agent terminals: it stays open while you click between agents and keeps its comparison, its open file and its folds when you come back. It is a tab of the bottom bar: it can be split with the other tabs of that bar (commands, terminals, databases, clusters, files), and also beside an agent: drag the tab onto the edge of an agent's pane, or click Pin this pane in the diff header (the pin is also in the tab's right-click menu). A pinned diff stays on screen while you click between agents, and the agents you open take the pane next to it. Drag its chip back onto the bottom bar to take it out. It has no window of its own: when the bottom bar is detached to a window, the diff goes with it, and when the agents are detached, a diff split beside an agent goes with them. The row's ... menu (or a right click) has Merge into <branch> (git cancels the merge on a conflict and nothing changes), Open a pull request (pushes the branch first if it was never pushed, then opens the prefilled page on GitHub, GitLab or Bitbucket) and Delete worktree..., which says what would be lost (uncommitted files, commits merged nowhere, agents still working there) and can delete the branch too. Open terminal here (the terminal icon shown when you hover a row, the row's ... menu, or the same icon in the header of a worktree's diff) opens a new terminal tab in the bottom bar, already in that checkout's folder, with no Open in card; the tab is named after the branch, and the Main row opens it at the project root. Open in external terminal (in the same menu) opens the system terminal app in that folder instead: Terminal on macOS, Windows Terminal (else PowerShell) on Windows, and on Linux your $TERMINAL or the first terminal found (GNOME Terminal, Konsole, Ptyxis, Xfce Terminal, kitty, Alacritty, WezTerm, Tilix, xterm). Clean up removes, after one confirmation, every worktree with no agent, no uncommitted change and no commit left to merge.
Under each answer of an agent, N files changed in this turn opens the diff of exactly what that turn wrote on disk (a snapshot of the checkout is taken when the turn starts and when it ends, without touching the git index). The Review mode diff also gets a Full diff view next to Diff and File.
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;falseleaves new worktrees untouched.worktreeSetupCommand(project, same row, Install command): the command run in a new worktree before the agent starts, for examplepnpm 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.newTicketsUseWorktree(project, Project settings > Defaults > Git > New tickets run in a separated worktree; folder default in Folder settings > Git): every new backlog ticket of the project starts with Code in a separated worktree for this task ticked: in the desktop form, in the phone form, when an agent files it withbacklog_createwithoutuseWorktree, and when it is imported from GitHub, JIRA, Linear, YouTrack and the other trackers (since 2026-11-13, see Import Tickets). A ticket can still untick it (useWorktree: falseover MCP). The project's value wins over the folder's. Absent = off, the form's usual behaviour. The phone reads the project's value only, not the folder's.newTicketsAutoMergeWorktree(project, same card, Auto-merge them when done, shown once the row above is on; folder default in Folder settings > Git): those tickets also start with Auto-merge into current branch when task is done ticked. Separate on purpose: a team that merges through a pull request keeps worktrees on and this one off. Absent = off.worktreeAutoCleanup(project, Project settings > Defaults > Git > Remove finished worktrees): deletes a worktree and its branch on its own when nothing would be lost: no agent (live or closed) pinned to it, nothing uncommitted, every commit merged into the base or Main, no backlog ticket still open on its branch, and an hour without activity. Checked when the project is opened and every 30 minutes while it is on screen; a toast says how many were removed. Absent = off: worktrees are kept for review. Local projects only (not a project whose agents run on an SSH host).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, andnode_modules,.git,.venv,dist,buildare never searched.
Agent tools (MCP)
backlog_create,backlog_update: acceptuseWorktree,worktreeBranchandautoMergeWorktreeon 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
The Changes screen of the phone has the same Worktree selector (Main plus each worktree with its branch) above the agent filter: the diff, the commit and the push act on the one picked. It needs an up-to-date desktop; an older desktop shows no selector and the screen reads the project as before. The branch switcher does not exist on the phone.
The same screen has a Worktrees button (the layers icon, shown when the repository has a linked worktree) that opens the overview: one row per checkout with its branch, agents and live status, changes, drift from the base and ticket. Tapping a row opens its diff, Uncommitted changes or Whole branch since its base, with the files grouped by folder or in a flat list as in the phone's Changes screen, and a file opens as the whole file with its changes in place (unchanged code folded, a tap unfolds it). It is read-only: merge, pull request and deletion are done on the computer that holds the worktrees, and commits, agent turns and Compare with stay on the desktop. One action is there since 2026-10-29: the terminal icon of a row opens a terminal of the computer already in that checkout's folder (named after its branch), shown on the phone and as a tab on the desktop.
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 a Code in a separated worktree for this task switch (and its Auto-merge into current branch when task is done) under the Agent field of Execution, on a new ticket only, pre-ticked from the project's New tickets run in a separated worktree setting (since 2026-11-11). The branch is named after the title. 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.
- By default a worktree is never deleted automatically; the folders accumulate under
.worktrees/. Turn on Remove finished worktrees (Project settings > Git) to have the ones with nothing left to lose removed on their own. Delete one from Changes > Worktrees (row menu, Delete worktree...) or with Clean up, or by hand (git worktree remove). Removing a worktree while an agent runs inside it breaks that agent's terminal: the delete confirmation names the agents still working there, and Clean up never touches a worktree that has one. - N files changed in this turn only covers turns that ran while the app was open (the snapshots live in memory on this computer), and a turn with no change on disk shows nothing.
- Open a pull request knows GitHub, GitLab (including a self-hosted GitLab connected in Settings) and Bitbucket; for another host it says so.
- 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
- I picked a saved agent with New worktree per agent. Can this one run in the project folder? Yes: open the Workspace card and choose Main, or another worktree. It applies to this agent only: the saved agent keeps its setting, and clicking the
agents/<name>branch brings the new worktree back. If the worktree cannot be created (no git repository, for example), the agent is still created in the project folder and a message tells you. - The Changes tab says "N unpushed commits" but I pushed them. The words next to the count say why.
compared with origin/x:origin/xdoes not have them, so they were pushed somewhere else or under another name.origin/x no longer exists: the remote branch was deleted, usually after a merge, and a squash or rebase merge gives the same work new commits.on no remote branch: no remote branch this repository knows about contains them. A crossed-out cloud on the Fetch button means the last fetch failed: hover it to read git's message. A frequent one is'refs/remotes/origin/fix' exists; cannot create 'refs/remotes/origin/fix/x', an old remote branch named like a folder, whichgit remote prune originrepairs. - How do I give an agent its own copy of the repo? Create a task on the board (New Task), open Execution > Advanced options, tick Code in a separated worktree for this task (the branch name fills itself in from the title) and, if you want, Auto-merge into current branch when task is done; then start the task. AgentsRoom creates the copy, installs the dependencies, copies the
.envfiles and starts the agent inside it. Video: https://youtu.be/3Xf4YJx2Euc - Can every new ticket use a worktree without ticking the box each time? Yes: Project settings > Defaults > Git > New tickets run in a separated worktree (or the same switch in Folder settings > Git for all the projects of a folder). New tickets then start with the box ticked, on the desktop, on the phone, when an agent creates them and when you import them from a tracker. Auto-merge them when done is a separate switch, leave it off if you merge through a pull request. A single ticket can still untick it.
- Every ticket with a Cyrillic title got the same branch
task, and two agents shared one worktree. Fixed on 2026-11-13. The branch filled in from the title now transliterates Cyrillic (Тестова задачаgivestestova-zadacha), an imported ticket is named after its key (proj-123-...), and a name another ticket of the board already holds gets-2,-3. A title in a script with no Latin reading (Chinese, Arabic...) still falls back totask, thentask-2. A branch you type or an existing worktree you pick is kept as is. - Is there a video that shows it? Yes, 1 min 25 s, filmed in the real app: https://youtu.be/3Xf4YJx2Euc
- 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,
.envfiles 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, and the agent form's From menu names it too.
- Can I create a worktree from another branch than the default one? Yes: in the agent form, New in the Worktree selector, then pick the branch in From. It applies to that worktree only; to change it for every new worktree, set Worktree base branch in Project settings > Git.
- Can AgentsRoom clean up old worktrees by itself? Yes, opt-in: turn on Remove finished worktrees in Project settings > Git. Only worktrees with no agent, nothing uncommitted, every commit merged and an hour without activity are removed, with their branch. Otherwise use Clean up in Changes > Worktrees.
- 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. When you are finished, delete it from Changes > Worktrees (row menu, Delete worktree...), or use Clean up to remove every finished one.
- Can I see all my worktrees and what each agent changed at once? Yes, since 2026-10-22: Changes > Worktrees lists every checkout with its agents, their live status, its changes and its distance from the base branch; a click opens its diff. On the phone, the layers button of the Changes screen opens the same list, read-only.
- The Changes tab only shows uncommitted files; how do I see what an agent already committed on its branch? Open Changes > Worktrees, click the worktree and pick Whole branch since its base in Compare: committed and uncommitted work against the merge-base, like a pull request. Each commit of the branch also opens its own diff.
- Can I keep a diff open while I click between agents? Yes: Open in a tab in the worktree diff puts it in a workspace tab next to the terminals, in the bottom bar. It splits with the other tabs of that bar and follows the bar when the bar is detached. Since 2026-10-29 the tab keeps the comparison, the file and the folds you had when you come back to it.
- Can I read an agent and its diff side by side? Yes, since 2026-11-02: drag the diff's tab from the bottom bar onto the left or right edge of the agent's pane, or click Pin this pane in the diff header. Pinned, the diff stays beside whichever agent you open next. It does not come back after a restart, like every tab of this kind.
- The file list cuts my long paths; can I see them? Yes: drag the edge of the list to widen it, or switch it to Tree by folder with the icon in the diff header. On the phone the list follows the same tree or flat choice as its Changes screen.
- Can I see the whole file instead of hunks? Yes: the worktree diff always shows the whole file with the changes in place; Collapse unchanged folds the unchanged code. In the Review mode, pick Full diff.
- How do I see what one agent turn changed? Under the agent's answer in the conversation view, click N files changed in this turn.
- How do I open a shell in an agent's worktree? Since 2026-10-27, with that agent focused (or the worktree picked in the Changes selector), click New terminal in the bottom bar: an Open in card offers Project folder or the worktree. Since 2026-10-29, faster: in Changes > Worktrees, hover the worktree's row and click the terminal icon (or Open terminal here in its ... menu, or in the header of its diff): the terminal opens straight in that folder, named after the branch. See Dev Terminals.
- Can I see the worktrees in the sidebar? No. Reach them from Changes > Worktrees, the backlog ticket form, or the Worktree selector of the agent modals.
- The Changes tab only shows the main checkout; how do I commit or push a worktree? Since 2026-10-12, pick the worktree in the Worktree selector at the top of the Changes tab: the diff, the commit, the pull and the push then act on it.
- Switching branch fails with "is already used by worktree at". git never checks out a branch that another worktree holds. The branch switcher marks those branches with the worktree's name and opens that worktree instead; the error message also has an Open this worktree button.
- 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
- Compare on several agents: the same request on 2 to 4 CLIs, one worktree each, keep the best.
- Backlog Task Board: where a ticket asks for its worktree.
- Agent Templates: the per-template worktree mode.
- Agent Teams: a ticket's team runs in the ticket's worktree.
- Agent Delegation: why the QA agent shares its master's checkout.
- AI Commit Messages: committing the branch before merging.
- Remote SSH Offload: worktrees on a project opened on an SSH server, and why a local checkout offloaded to one has none.
- AgentsRoom MCP: the tools an agent started in a worktree now keeps.
- Dev Terminals: a new bottom terminal can open in the worktree.
- External Git Client: open a worktree in your own Git client (GitHub Desktop, Sublime Merge, Tower...).