Why parallel agents need a worktree each
Checked against the Orcyx source tree at c339cf993 on 2026-09-14. The git behaviour below is standard git; the Orcyx behaviour restates the seats page. Where this page describes something the build does not do yet, it says so in place rather than describing the intention.
A git worktree is a second working directory attached to the same repository, checked out on its own branch. Parallel AI coding agents need one each because two agents in one checkout read each other's half-finished files, a type check run by one fails on the other's in-flight edit, and a command that discards local changes destroys work its author never saw. Separate worktrees remove that shared surface without the cost of separate clones. Orcyx, an agentic development environment, automates the setup.
A worktree is not a clone. It shares the object database with the main checkout, so it costs a working tree rather than a repository, and it appears in the repository's worktree list rather than as a detached copy on disk.
The commands
Four git commands cover the lifecycle. Git refuses to check out one branch in two worktrees at once, which is the property that keeps two agents off the same branch.
| Command | What it does for an agent |
|---|---|
| git worktree add -b agent/task ../agent-task | Creates a new working directory on a new branch for one agent. |
| git worktree list | Shows every checkout of the repository and the branch each one holds. |
| git worktree remove ../agent-task | Deletes the working directory once its branch is merged or abandoned. |
| git worktree prune | Drops registrations whose directory no longer exists, for example after a crash or a reboot. |
What a worktree does not share
A worktree gives an agent its own files and its own branch. It does not give the agent a built project, and it does not share everything between checkouts. Three gaps catch people out.
- Installed dependencies. A new worktree has the tracked files only, so an agent in it cannot build until dependencies exist there. Orcyx links the installed dependency directories into the seat instead of copying them, so a seat never pays for an install.
- Untracked hook directories. If the repository points git's hooks path at a directory that is not tracked, a worktree made by hand has no hooks and every commit in it passes unchecked. Orcyx copies that directory on creation; by hand you must copy it before the first commit.
- The stash stack. It is shared by every worktree in the repository. A bare stash push in one worktree can capture another agent's in-flight work, and a bare pop can restore it into the wrong place.
Where parallel agents still collide
Worktrees stop agents overwriting each other's files. They do not stop two agents solving the same problem, because that conflict moves to merge time. In the seats rehearsal, two agents that each added the same file produced an add/add conflict at merge, reconciled by rebasing in the second agent's own worktree. Plan for that reconciliation as part of the task.
Commit path-restricted, naming only the files you own, and avoid commands that discard or relocate uncommitted changes across the whole tree: hard resets, path checkouts, clean and a bare stash. In a repository where other agents are mid-edit those commands reach work the author never saw.
Merging each agent's branch back
An agent's work reaches the main branch by merging its branch from the main checkout, not by copying files across. If the branch is behind, rebase in the agent's own worktree first. The first merge wins; a later one that conflicts rebases and retries, and nobody resolves a conflict by editing the main checkout.
Do not pipe the merge through another command. The pipeline's exit status becomes the last command's, so a merge that failed on index-lock contention can read as a success while the merge is gone. Check that the remote branch actually moved.
What Orcyx automates
Orcyx runs the same sequence for every agent pane: prune stale registrations, add a worktree on a new branch named for the workspace and the pane, link the dependency directories, and copy the hook shims. Creating the worktree is essentially all of the cost; wiring it so it can build is orders of magnitude cheaper. The measured timings are on the seats and worktrees page.
In a swarm run each role that changes code gets its own git worktree for the run, and a finished role's changed files get the advisory review scan before the work reaches you. Orcyx does not run models: the worktree holds whichever coding CLI you seat in it, including Claude Code and Codex side by side.