Guide
A git worktree workflow for coding agents
An agent that edits files needs a checkout of its own. Everything else in this workflow — branches, diffs, merges — follows from that one decision.
The problem with one checkout
A working copy is a mutable thing. Two sessions that share it will overwrite each other’s edits, fight over the index, and produce a diff that belongs to neither of them. The failure is quiet: each agent believes it is working on the project, and the file it just wrote is gone.
Stashing and switching branches between sessions is not a fix, it is the same collision with extra steps — an agent that is mid-task cannot survive having the files pulled out from under it.
The fix, in four commands
A git worktree is a second checkout of the same repository with its own branch, sharing the object database. It is the mechanism this whole category of tooling is built on, and it is worth knowing by hand:
- git worktree add ../task-a -b task-a — a new checkout on a new branch, next to the repo.
- cd ../task-a && your-agent — run the agent in its own copy.
- git worktree list — which checkouts exist and what each is on.
- git worktree remove ../task-a — throw the checkout away when the branch is merged.
What goes wrong next
The single most common mistake is letting the agent run in the repository root "just for this one task". That is the collision you were avoiding, and it always happens on the task that matters.
The second is forgetting that a worktree is not a sandbox for the environment: shared service ports, a single local database and a global cache are all still shared, and two agents running migrations against one database will corrupt it. Worktrees separate files, not machines.
The third is drift. Without a habit of removing worktrees when their branch is merged, a repository accumulates stale checkouts that quietly hold the branch names you want to reuse.
Where a workspace fits
Everything above can be done by hand, and if one agent is running at a time, doing it by hand is fine. The arithmetic changes at three: three checkouts, three branch names, three diffs to read, and a merge order to decide.
That is the layer Nix Agents adds — it creates the worktree, names the branch after the task, keeps the diff per worktree and holds the finished ones in a merge queue. The commands above are still what is happening underneath, which is why it is worth knowing them either way.
Questions
- Does a worktree duplicate the repository?
- No. Worktrees share the object database and each has only its own working copy and index, so a second worktree costs the size of the checked-out files, not a clone.
- Can two worktrees be on the same branch?
- No — git refuses to check out a branch that is already checked out elsewhere. That restriction is the feature: it is what guarantees two agents cannot be editing the same branch at once.
- Do worktrees work with submodules and monorepos?
- They work with ordinary git repositories, including monorepos. Submodules need their own initialisation inside each worktree, which is a git behaviour rather than a tool one.