[{"data":1,"prerenderedAt":49},["ShallowReactive",2],{"doc:en:worktrees":3},{"title":4,"lede":5,"html":6,"headings":7},"One worktree per agent","A worktree gives each agent its own folder and its own branch, so that several agents can work on the same repository without getting in each other’s way. This page explains how to turn it on, set it up, merge its work and clean it up.","\u003Ch2 id=\"what-a-worktree-is-for\">What a worktree is for\u003C\u002Fh2>\n\u003Cp>A git worktree is a second working folder of the same repository, on its own branch. With the “One worktree per agent” option, each new agent gets its own: its changes stay apart, neither the other agents nor your own folder see them until you merge them, and the files panel lists them separately (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fgit\u002F\">Git\u003C\u002Fa>).\u003C\u002Fp>\n\u003Cp>Without a worktree, all of a project’s agents work in the project folder and their changes get mixed together: Escouade then attributes them to each agent based on its edits.\u003C\u002Fp>\n\u003Cp>The agents of \u003Ca href=\"\u002Fen\u002Fdocs\u002Fboard\u002F\">Kanban\u003C\u002Fa> tickets always work in a worktree of their own, on the ticket’s branch, whether the option is on or not. They follow the same folder, copied-files and command settings as the others.\u003C\u002Fp>\n\u003Ch2 id=\"turning-it-on\">Turning it on\u003C\u002Fh2>\n\u003Cp>The option is set per project, and only affects agents created afterwards: the ones that already exist stay where they are. Three places offer it:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>the “New project” window, with the “One git worktree per agent” switch (off by default);\u003C\u002Fli>\n\u003Cli>a right-click on the project’s tab, then “Turn on a worktree per agent” or “Turn off a worktree per agent” (the entry says “new agents”);\u003C\u002Fli>\n\u003Cli>Settings › Projects, “Git” group, “One worktree per agent”.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>The project folder must be on a branch that has at least one commit: a brand-new repository with no commit can’t have a worktree yet. When a worktree can’t be created, the agent works in the project folder and the conversation shows “Worktree not created, the agent works in the project’s folder: …” with the reason.\u003C\u002Fp>\n\u003Ch2 id=\"where-it-goes-and-what-it-s-called\">Where it goes and what it’s called\u003C\u002Fh2>\n\u003Cp>Four project settings decide the location and the names (Settings › Projects, “Git” group). The full list of settings is in \u003Ca href=\"\u002Fen\u002Fdocs\u002Fsettings-projects\u002F\">the project settings\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Setting\u003C\u002Fth>\n\u003Cth>Default\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>“Worktrees folder”\u003C\u002Ftd>\n\u003Ctd>\u003Ccode class=\"key\">.claude\u002Fworktrees\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Where new worktrees go: relative to the project folder (\u003Ccode class=\"key\">..\u002Fapp-worktrees\u003C\u002Fcode>, \u003Ccode class=\"key\">.worktrees\u003C\u002Fcode>), to your home folder (\u003Ccode class=\"key\">~\u002Fworktrees\u002Fapp\u003C\u002Fcode>), or a full path. Under the field, “The next one: …” shows where the next one would go. It can’t be the project’s own folder, a folder that holds it, or a folder inside \u003Ccode class=\"key\">.git\u003C\u002Fcode>. Worktrees made already stay where they are.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>“Agents’ branch prefix”\u003C\u002Ftd>\n\u003Ctd>\u003Ccode class=\"key\">escouade\u002F\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A new agent’s branch is called \u003Ccode class=\"key\"><prefix><name>\u003C\u002Fcode>. Empty, it is its name alone.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>“Tickets’ branch prefix”\u003C\u002Ftd>\n\u003Ctd>\u003Ccode class=\"key\">ticket\u002F\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A ticket’s branch, the one its pull request comes from, is called \u003Ccode class=\"key\"><prefix><key>\u003C\u002Fcode>. Empty, it is its key alone.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>“Files copied into worktrees”\u003C\u002Ftd>\n\u003Ctd>\u003Ccode class=\"key\">.env*\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The files that git ignores and that a new worktree takes from the project (see \u003Ca href=\"#copied-files\">below\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>The worktree’s folder is \u003Ccode><worktrees folder>\u002F<agent name>\u003C\u002Fcode>, on a new branch \u003Ccode><prefix><agent name>\u003C\u002Fcode>. If either already exists, Escouade adds \u003Ccode class=\"key\">-2\u003C\u002Fcode>, \u003Ccode class=\"key\">-3\u003C\u002Fcode>… An agent is first called \u003Ccode class=\"key\">agent-1\u003C\u002Fcode>, \u003Ccode class=\"key\">agent-2\u003C\u002Fcode>…; when Escouade names it from its first message (for example \u003Ccode class=\"key\">refacto-auth\u003C\u002Fcode>), its branch becomes \u003Ccode>escouade\u002Frefacto-auth\u003C\u002Fcode> if that name is free, while the folder keeps its first name. A name you give yourself never changes the branch. The agent’s card shows the branch without its prefix (\u003Ccode>⎇ refacto-auth\u003C\u002Fcode>), and its full name on hover.\u003C\u002Fp>\n\u003Cp>The worktree starts from the commit the project folder is on at that moment. That folder’s branch becomes the agent’s \u003Cstrong>base branch\u003C\u002Fstrong>: it is the one that the merge and “Integrate” aim at.\u003C\u002Fp>\n\u003Cp>When the worktrees folder is inside the repository (the default), Escouade adds it to the repository’s \u003Ccode class=\"key\">.git\u002Finfo\u002Fexclude\u003C\u002Fcode> file: the worktrees don’t show up in the project’s changes. A folder that already holds files git tracks is refused: “The worktrees folder … holds files git tracks: pick another one in the project’s settings.”\u003C\u002Fp>\n\u003Ch2 id=\"copied-files\">Copied files\u003C\u002Fh2>\n\u003Cp>A file like \u003Ccode class=\"key\">.env\u003C\u002Fcode>, which git ignores, doesn’t exist in a fresh worktree. Right after the worktree is created, Escouade copies into it the project’s files that git ignores and that match a pattern of the “Files copied into worktrees” setting.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>One pattern per line, with \u003Ccode class=\"key\">*\u003C\u002Fcode> and \u003Ccode class=\"key\">?\u003C\u002Fcode> inside a name and \u003Ccode class=\"key\">**\u003C\u002Fcode> to cross folders: \u003Ccode class=\"key\">.env*\u003C\u002Fcode> takes the files at the root, \u003Ccode class=\"key\">**\u002F.env*\u003C\u002Fcode> those of every folder. The default is \u003Ccode class=\"key\">.env*\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>Only files git ignores are copied, so none of them can end up in a commit. A file that git tracks is never copied.\u003C\u002Fli>\n\u003Cli>The copies show up in the file tree of the \u003Ca href=\"\u002Fen\u002Fdocs\u002Feditor\u002F\">editor\u003C\u002Fa>, greyed out (“Ignored by git”). A direct commit never takes them.\u003C\u002Fli>\n\u003Cli>If a copy fails, the conversation says so (“Files not copied into the worktree: …”) and the agent works without that file.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"setting-up-the-worktree\">Setting up the worktree\u003C\u002Fh2>\n\u003Cp>A fresh worktree has no dependencies installed and no generated code. The “Worktrees” group of the project settings lists the commands Escouade runs to set it up, in the “When a worktree opens” list: they run in order, in the new worktree, before the agent’s first message, and its messages wait for them to finish.\u003C\u002Fp>\n\u003Cp>Each command has a shell (the first shell detected by default), a command line (for example \u003Ccode>npm ci\u003C\u002Fcode>) and a “Subfolder” of the worktree (blank, it is the root). “+ Add a command” adds one, the × deletes it. To change the order, use the command’s ↑ and ↓ buttons, or \u003Ccode class=\"key\">Alt+↑\u003C\u002Fcode> and \u003Ccode class=\"key\">Alt+↓\u003C\u002Fcode> (\u003Ccode class=\"key\">⌥↑\u003C\u002Fcode> and \u003Ccode class=\"key\">⌥↓\u003C\u002Fcode> on macOS) from any field of the command. An empty command is skipped.\u003C\u002Fp>\n\u003Cp>The commands get these environment variables:\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Variable\u003C\u002Fth>\n\u003Cth>Value\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">ESCOUADE_PROJECT_DIR\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The project folder.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>ESCOUADE_WORKTREE_DIR\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The worktree’s folder.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">ESCOUADE_BRANCH\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The worktree’s branch.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode class=\"key\">ESCOUADE_PORT_BASE\u003C\u002Fcode>, \u003Ccode class=\"key\">ESCOUADE_PORT_END\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The ports reserved for a ticket’s worktree, when it has some (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Ftesting\u002F\">testing\u003C\u002Fa>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>The proxy of the “HTTP(S) proxy” setting is passed to the commands when “Also apply the proxy to the built-in terminals” is on (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fsettings-network\u002F\">the network settings\u003C\u002Fa>). A command that runs past 20 minutes is stopped.\u003C\u002Fp>\n\u003Ch3 id=\"following-the-setup\">Following the setup\u003C\u002Fh3>\n\u003Cul>\n\u003Cli>The agent’s card says “Setting up…”; its tooltip gives the command in progress.\u003C\u002Fli>\n\u003Cli>The conversation shows “Setting up the worktree · npm ci — your messages will be sent once it’s done.” The “Show output” button unfolds the last lines of what the command writes, live. The output follows the new lines while you are at the bottom, and stays put if you scroll up.\u003C\u002Fli>\n\u003Cli>A message you send during the setup waits: it goes out once the setup is finished.\u003C\u002Fli>\n\u003Cli>At the end, the conversation notes “Worktree set up (3 commands, 12 s).”\u003C\u002Fli>\n\u003Cli>The full output of the last setup, command after command, is written to \u003Ccode class=\"key\">~\u002F.escouade\u002Flogs\u002F\u003C\u002Fcode>, one file per agent named \u003Ccode><agent identifier>-setup.log\u003C\u002Fcode>. It is replaced at each setup and deleted with the agent.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Archiving or deleting the agent during its setup stops it.\u003C\u002Fp>\n\u003Ch3 id=\"when-a-command-fails\">When a command fails\u003C\u002Fh3>\n\u003Cp>The first command that fails stops the setup: the following ones don’t run. The conversation shows a warning, for example “The worktree setup failed on \u003Ccode>npm ci\u003C\u002Fcode> (code 1).”, followed by the last 30 lines of the output and the path of the full output (“Full output: …”). The failure can also come from a subfolder that doesn’t exist in the worktree, from a command that doesn’t start, or from a command stopped after 20 minutes.\u003C\u002Fp>\n\u003Cp>The agent is told in its first message, with the command that failed and its last lines, and it starts all the same: it can take it into account.\u003C\u002Fp>\n\u003Ch3 id=\"fill-in-automatically\">Fill in automatically\u003C\u002Fh3>\n\u003Cp>“✦ Fill in automatically”, at the top of the “Worktrees” group, asks Claude to read the project (manifests, lockfiles, README…) and suggest the commands. It changes nothing: it only has reading tools, and it has 4 minutes at most. Its suggestion appears apart, under “Suggested worktree commands”, with each command in full, its shell and its folder:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>“Replace the commands” replaces both lists of the draft (setup and teardown). Nothing is kept until you click “Save” in the settings window;\u003C\u002Fli>\n\u003Cli>“Ignore” drops the suggestion.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Claude suggests eight commands at most per list. A command on several lines, with invisible characters, with a run of 24 spaces or more, or of over 300 characters is left out, and the message that follows the reading says so (“2 commands suggested, 1 left out (invisible characters or too long): review them before saving.”).\u003C\u002Fp>\n\u003Cdiv class=\"callout warning\">\u003Cp class=\"callout-title\">Warning\u003C\u002Fp>\u003Cp>Once saved, these commands run on their own in every new worktree. Read each one in full before saving.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"tearing-down-the-worktree\">Tearing down the worktree\u003C\u002Fh2>\n\u003Cp>The “Before a worktree is removed” list holds what must be undone outside the worktree before deleting it: a database or containers that the setup created for it. Most often, it is empty. It is edited like the setup list, and is also filled by “✦ Fill in automatically”.\u003C\u002Fp>\n\u003Cp>These commands run when an agent is deleted with its worktree, and when the Kanban cleans up a ticket’s worktree. Each one runs even if the previous one failed, with 5 minutes at most, and their output isn’t shown. If the project uses isola (an \u003Ccode class=\"key\">.isola.toml\u003C\u002Fcode> file), \u003Ccode>isola destroy\u003C\u002Fcode> runs afterwards. A problem is reported once the agent is deleted: “Agent deleted, but the worktree teardown failed on …”.\u003C\u002Fp>\n\u003Ch2 id=\"working-on-a-branch-that-already-exists\">Working on a branch that already exists\u003C\u002Fh2>\n\u003Cp>An agent can also work in a worktree on a branch that already exists, instead of creating a new one:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>“New agent on a branch…” in the menu of the ▾ button, to the right of “New agent”, opens the branch picker (“Choose a branch”);\u003C\u002Fli>\n\u003Cli>in the status bar’s branch picker, a right-click on a branch offers “Start an agent on this branch”;\u003C\u002Fli>\n\u003Cli>in a ticket’s form, the “Branch” field offers “Take up an existing branch…”.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>A remote branch is taken up through the local branch that tracks it, created if there is none. The project folder isn’t touched. Three branches are refused, with the reason: the project folder’s branch, the Kanban’s target branch (tickets are merged into it), and one that another worktree already holds.\u003C\u002Fp>\n\u003Cp>That branch is the agent’s, but Escouade never creates or deletes it: when you delete the agent, the box offers “Also delete the worktree (the branch … is kept)”. Its base branch is the Kanban’s target branch if it exists, otherwise the project folder’s branch. For a ticket, the entry’s tooltip says “Escouade never deletes this branch, even once the ticket is approved.” Branches are covered in \u003Ca href=\"\u002Fen\u002Fdocs\u002Fbranches\u002F\">the branches page\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"merging-into-the-base-branch\">Merging into the base branch\u003C\u002Fh2>\n\u003Cp>When an agent’s work suits you, you merge it into its base branch from the files panel:\u003C\u002Fp>\n\u003Col>\n\u003Cli>The agent must have committed its work (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fgit\u002F\">Git\u003C\u002Fa>). The merge only takes commits.\u003C\u002Fli>\n\u003Cli>In the panel, “Uncommitted” tab, “This agent” button, click “Merge escouade\u002Frefacto-auth → main…”.\u003C\u002Fli>\n\u003Cli>The window asks “Merge escouade\u002Frefacto-auth into main?” and says the agent’s commits are merged into the project’s “main” branch. The “Squash (a single commit)” box is unchecked by default. Click “Merge”.\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>The merge happens in the project folder.\u003C\u002Fp>\n\u003Cdiv class=\"table\">\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Choice\u003C\u002Fth>\n\u003Cth>Result\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Without “Squash”\u003C\u002Ftd>\n\u003Ctd>A merge commit (\u003Ccode>Merge branch 'escouade\u002Frefacto-auth'\u003C\u002Fcode>) that keeps all the agent’s commits.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>With “Squash (a single commit)”\u003C\u002Ftd>\n\u003Ctd>A single commit, named after the agent, that lists the subjects of the commits it groups.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\u003C\u002Ftable>\u003C\u002Fdiv>\n\u003Cp>Escouade refuses the merge, with a message, in these cases:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>the agent has uncommitted files (“The agent has 2 uncommitted files: ask it to commit before merging.”);\u003C\u002Fli>\n\u003Cli>the project folder has uncommitted changes to tracked files: commit them or stash them;\u003C\u002Fli>\n\u003Cli>the agent’s branch has no new commit (“Nothing to merge”);\u003C\u002Fli>\n\u003Cli>the base branch no longer exists.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>If the project folder isn’t on the base branch, a question appears: “Switch to “main”?” It says which branch the project is on. “Switch and merge” switches the folder to the base, then merges.\u003C\u002Fp>\n\u003Cp>A merge with conflicts is aborted: the project folder stays as it was and an error message appears. In that case, first bring the base into the agent’s branch with “Integrate main”, which hands the conflicts to the agent (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fbranches\u002F\">branches\u003C\u002Fa>), then start again.\u003C\u002Fp>\n\u003Cp>The merge removes neither the agent’s worktree nor its branch. To tidy them up, delete the agent with its worktree (see below); to clean up the branches already merged in one go, use “Merged branches” in \u003Ca href=\"\u002Fen\u002Fdocs\u002Fbranches\u002F\">the branch picker\u003C\u002Fa>. For Kanban tickets, the approval takes care of the commit, the merge or the pull request according to the settings (see \u003Ca href=\"\u002Fen\u002Fdocs\u002Fsettings-board\u002F\">the Kanban settings\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2 id=\"archiving-restoring-deleting\">Archiving, restoring, deleting\u003C\u002Fh2>\n\u003Cp>The actions are in the menu of a right-click on the agent’s card.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>“Archive” stops the agent and keeps its conversation. Its worktree and its branch stay on disk. The confirmation only appears for an agent whose ticket is in progress or to review.\u003C\u002Fli>\n\u003Cli>“Restore” brings an archived agent back. If its worktree folder has disappeared in the meantime, for example after a pull request or a push, Escouade recreates it from its branch, copies the project’s files again and runs the setup again. If another worktree has taken its folder, its own is recreated beside it (\u003Ccode class=\"key\">-2\u003C\u002Fcode>) and the conversation says so. If the branch no longer exists (merged then deleted), the agent stays as it is.\u003C\u002Fli>\n\u003Cli>“Delete…” asks for confirmation. The box “Also delete the worktree and the branch escouade\u002Frefacto-auth” is checked by default. Checked, Escouade stops the agent, runs the teardown commands, removes the worktree’s folder, then the branch. Unchecked, the agent disappears from Escouade and the worktree and the branch stay on disk. If files of that worktree are open and unsaved in the editor, the window warns that they will be lost.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cdiv class=\"callout warning\">\u003Cp class=\"callout-title\">Warning\u003C\u002Fp>\u003Cp>The agent’s branch is deleted even if it hasn’t been merged: its commits then exist nowhere else. Merge it first if you want to keep its work.\u003C\u002Fp>\n\u003C\u002Fdiv>\n\u003Cp>If the cleanup runs into a problem (a process still holding the folder, a teardown that fails), the agent is deleted all the same and a message reports it afterwards. Closing a project doesn’t touch its worktrees on disk.\u003C\u002Fp>\n\u003Ch2 id=\"duplicating-an-agent\">Duplicating an agent\u003C\u002Fh2>\n\u003Cp>“Duplicate the conversation” (the agent’s menu) copies an agent that has a worktree into a worktree of its own, created from the commit the original is on, on a new branch whose name builds on the copy’s. The original’s uncommitted changes aren’t in it, and the conversation says so. See \u003Ca href=\"\u002Fen\u002Fdocs\u002Fmanaging-agents\u002F\">agents\u003C\u002Fa>.\u003C\u002Fp>\n",[8,12,15,18,21,24,28,31,34,37,40,43,46],{"id":9,"text":10,"depth":11},"what-a-worktree-is-for","What a worktree is for",2,{"id":13,"text":14,"depth":11},"turning-it-on","Turning it on",{"id":16,"text":17,"depth":11},"where-it-goes-and-what-it-s-called","Where it goes and what it’s called",{"id":19,"text":20,"depth":11},"copied-files","Copied files",{"id":22,"text":23,"depth":11},"setting-up-the-worktree","Setting up the worktree",{"id":25,"text":26,"depth":27},"following-the-setup","Following the setup",3,{"id":29,"text":30,"depth":27},"when-a-command-fails","When a command fails",{"id":32,"text":33,"depth":27},"fill-in-automatically","Fill in automatically",{"id":35,"text":36,"depth":11},"tearing-down-the-worktree","Tearing down the worktree",{"id":38,"text":39,"depth":11},"working-on-a-branch-that-already-exists","Working on a branch that already exists",{"id":41,"text":42,"depth":11},"merging-into-the-base-branch","Merging into the base branch",{"id":44,"text":45,"depth":11},"archiving-restoring-deleting","Archiving, restoring, deleting",{"id":47,"text":48,"depth":11},"duplicating-an-agent","Duplicating an agent",1791926756259]