Git Worktrees for AI Coding Agents: A Setup Guide
One repository, several working folders. How git worktrees let more than one AI coding agent work at the same time without colliding.
Git worktrees for AI coding agents are a simple fix for agents colliding. A git worktree is a second working folder attached to the same repository, with its own checked-out branch. Give each AI coding agent its own worktree and they can edit files at the same time without stepping on each other, because each one sees a separate copy of the files while sharing one history. That is the whole idea, and it removes the most common collision when you run more than one agent.
Why agents collide without them
Two agents pointed at one folder share one set of files and one checked-out branch. One agent's half-finished edit shows up in the other's test run. A branch switch by one changes the files under the other. The usual workaround, cloning the repository twice, works but wastes disk and leaves you with histories that drift apart.
Worktrees solve this inside one repository. The git documentation describes the command as managing multiple working trees attached to the same repository. If you run parallel agents already, this fits alongside the habits in running multiple AI coding agents in parallel.
Set one up
From your main checkout, create a worktree and a new branch in one command:
git worktree add -b agent/fix-login ../myapp-fix-loginThe -b flag creates a new branch, here agent/fix-login, starting from the current commit, and checks it out into the new folder ../myapp-fix-login. By default, git refuses if that branch already exists.
Make a second one for another task:
git worktree add -b agent/add-export ../myapp-add-exportNow point one agent at each folder. List what you have at any time:
git worktree listThe main worktree is listed first, followed by each linked one.
What is shared and what is not
Shared by all worktrees | Separate in each worktree |
|---|---|
Commit history and branches | The checked-out files |
Repository config |
|
Stashes and tags | Uncommitted edits |
Because history is shared, a commit one agent makes is visible to the others as soon as it exists. That is helpful for merging and a reason to keep branches short. Separate working files do not remove merge conflicts, they only move them to the moment you merge. Our guide to handling merge conflicts with AI coding agents covers that step.
The two errors you will hit
Same branch in two places. Git will not check out one branch in two worktrees at once. It refuses to add a worktree for a branch that another worktree already has, unless you pass --force. The refusal protects you, so give every agent its own branch rather than forcing it.
Removing a worktree with leftovers. When an agent finishes, remove its folder with:
git worktree remove ../myapp-fix-loginPer the documentation, only clean worktrees can be removed, meaning no untracked files and no modified tracked files. Build output and logs count as untracked, so removal can fail even when the code is merged. Add --force only after you have checked nothing there is worth keeping. If you delete the folder by hand instead, clean up the leftover record with git worktree prune.
A routine that works
Create one worktree and branch per task, named for the task.
Give the agent its folder as the working directory and tell it which branch it is on.
Install dependencies in each worktree if your project needs them, since
node_modulesis not shared.Review the diff and merge one branch at a time.
Remove the worktree and delete the merged branch.
Keep secrets and local config out of commits regardless of setup, and see AI coding agent gitignore mistakes for the usual leaks. For the basics of the branches themselves, start with what a git branch is, and for choosing the tools around your agents, see the AI coding tools guide.
Frequently asked questions
What is a git worktree?
A git worktree is an extra working folder linked to an existing repository, with its own checked-out branch. It shares the repository's history but keeps its own files.
Can two AI agents use the same git worktree?
They can, but they will collide, because they share the same files and branch. Give each agent its own worktree.
How do I delete a git worktree?
Run git worktree remove <path>. It only works on clean worktrees unless you add --force. Use git worktree prune to clear records for folders that were deleted by hand.
Is a worktree the same as cloning the repository again?
No. A clone has its own copy of the history. A worktree shares one history with the original, so it uses less disk and sees new commits immediately.
How did this land?
About the author
Developer Advocate
Steve builds something with Swarmz every week and writes up what worked, what broke, and what he'd do differently. Tutorials and hands-on guides are his lane.
