Git worktrees: the foundation for running multiple AI agents without conflicts

You launch two agents on the same repo. One edits package.json, so does the other. Thirty seconds later your code is in a state nobody can merge.

That's not a bug in your agents. It's that they all work in the same folder.

The fix is a tool Git has had for years and almost nobody uses: git worktree.

The problem: 3 agents, 1 repo, impossible merge

A normal Git repo is one folder with one branch checked out at a time. You work on main, you switch branches, the whole folder flips.

Now drop three autonomous agents into that folder. They write at the same time. Agent A creates a file, agent B runs git checkout to start clean and wipes A's work in progress. You end up with half-written files, a trashed index, and conflicts that take longer to untangle than if you'd coded it yourself.

Parallelism saves you time only if the agents don't touch each other.

What a git worktree is

A worktree is a second working folder attached to the same repo.

Same history, same remote, but each worktree has its own branch checked out and its own files on disk. You can have five side by side, each on a different branch, without them getting in each other's way.

One .git, several workspaces. That's it.

One worktree per agent, in practice

Here's the setup. From your repo:

git worktree add ../project-auth -b feature/auth
git worktree add ../project-billing -b feature/billing
git worktree add ../project-export -b feature/export

You just created three folders, each on its own branch. You start an agent in each:

cd ../project-auth && claude
cd ../project-billing && codex

Each agent has its folder, its branch, its files. The auth agent will never see what the billing agent does. No collision possible.

When a feature is ready, you review its branch and merge. Then you clean up:

git worktree remove ../project-auth

The folder is gone, the branch stays in your history. Clean.

The 3 traps to know

First trap, the shared central file. If two features both have to touch the same routes.ts or the same database schema, worktrees don't save you, you'll get the conflict at merge time. One agent touches the files everyone shares, the others wait or work around it.

Second, branches that drift. While your agents work, main moves on. Three days later your branches are behind and merging gets painful. Rebase early and often, or keep sessions short.

Third, forgotten cleanup. Each worktree is a real folder on your disk. Ten a day with no cleanup, and your parent folder becomes unreadable. git worktree list shows what's lying around, git worktree prune removes the dead ones.

The real question: who watches the five folders?

Worktrees solve file collisions. They don't solve your mental load.

You've got five folders, five agents, five terminals. Which one is waiting on your review? Which one finished ten minutes ago while you were looking elsewhere? Which one crashed?

That's where one worktree per agent hits its limit if you stay in the terminal. You solved the technical conflict, but you multiplied the windows to watch.

AgentsRoom puts each agent on a tile, with its status and color, no matter which worktree it runs in. An agent that's waiting turns red and pings you. Read how to run 3 to 8 agents in parallel without losing track for the full method on top of worktrees.

What to take away

One agent, one worktree, one branch. That's the base rule of serious multi-agent work.

The commands fit in three lines, the benefit is immediate: your agents stop overwriting each other. Add a view that tells you which one needs you, and you can really hold five jobs in parallel without losing your mind.