The moment you run a second coding agent in the same repository, you need git worktrees. Two agents in one folder will edit the same files, run each other's half-finished changes, and leave you a diff nobody can explain.
A worktree fixes that in one command. This guide covers the commands, and the five things that break once you have a few of them.
What a worktree is
A worktree is a second working folder for the same repository. It shares the repository's history and objects with your main checkout, but has its own files and its own checked-out branch. Edits in one never appear in the other until you commit and merge.
For agents, that means: one task, one worktree, one agent. Each works on its own copy of every file, and you merge their branches like a teammate's.
The commands
# a new branch and a folder for it, next to your checkout
git worktree add -b fix-login ../myapp-fix-login
# start your agent there
cd ../myapp-fix-login
claude # or: codex, gemini
# see every worktree
git worktree list
# when the branch is merged
git worktree remove ../myapp-fix-login
git branch -d fix-login
# if you deleted a worktree folder by hand
git worktree prune
A branch can be checked out in only one worktree at a time. If git refuses with "already checked out", that branch lives in another worktree; give the new task its own branch.
The five things that break, and the fixes
1. Your .env isn't there
Worktrees contain tracked files only. Secrets, local config and anything in .gitignore stay in your main checkout. Keep a short script that makes a worktree and copies them in:
#!/bin/sh
# usage: ./new-task.sh fix-login
set -e
dir="../$(basename "$PWD")-$1"
git worktree add -b "$1" "$dir"
cp .env "$dir/" 2>/dev/null || true
2. Dependencies aren't installed
node_modules, virtualenvs and build caches are per folder. The agent's first command will fail until it installs them. Two fixes: tell the agent in your instructions file (CLAUDE.md, AGENTS.md) to install dependencies first, and use a package manager with a shared store (pnpm, uv, Bun) so a fresh install takes seconds.
3. Ports collide
Two worktrees running the dev server both want port 3000. Read the port from the environment and set a different one per worktree, for example in that worktree's .env.
4. Databases and containers collide
Two worktrees running the same Docker Compose file share container names and volumes, so one agent's migration lands in the other's database. Set COMPOSE_PROJECT_NAME per worktree, or point each at its own database name.
5. Worktrees pile up
A forgotten worktree is a forgotten branch and a folder of disk space. Run git worktree list at the end of the week, and remove what's merged. Before removing one, check it has nothing uncommitted (git -C <folder> status) and nothing unpushed, since that work exists nowhere else.
Things worth knowing
- A worktree starts from a commit. Uncommitted changes in your main checkout aren't in it. Commit or stash first if the agent needs them.
- Review is a merge. Treat each agent's branch as a pull request: read the diff, run the tests, merge or throw it away. Throwing a branch away is cheap, which is half the point.
- Comparing agents is easy. Give two agents the same prompt in two worktrees and diff their branches. It's the fastest way to learn which agent suits which kind of task.
Doing it without the script
I build Moontors, a free desktop app for running coding agents side by side, so this part is about my own tool.
It does all of the above when you turn on Run in a new worktree while creating a session: it makes the worktree outside your folders, on a branch if you name one, copies in the untracked files your project lists (such as .env), and starts the session there. Archiving the session removes the worktree, and asks first if it holds uncommitted changes or unpushed commits. It works the same for Claude Code, Codex and Gemini CLI, on macOS, Windows and Linux.
The details are in its guide: How to use git worktrees for AI coding agents.
Script or app, the rule is the same: one agent, one worktree, one branch to review.
AI did the writing, I did the reading, and we both took credit.
Top comments (0)