Git worktrees for coding agents.

What a worktree is

A repository normally has one working folder: the checkout you cloned. git worktree adds more. Each extra worktree is a separate folder with its own checked-out branch, its own staged changes and its own uncommitted files. All of them share one history, so a commit made in any worktree is visible from the others right away, without a push or a fetch.

Git allows a branch to be checked out in only one worktree at a time. That rule is what keeps two agents off the same branch.

Why agents need them

An agent reads files, edits them and runs tests in the folder it starts in. Start two agents in the same checkout and each one sees the other's half-finished edits. Tests fail for reasons neither agent caused, and a git checkout or git stash from one agent changes the files under the other.

Put each agent in its own worktree and those problems go away. Each agent works on its own branch, and you merge the results the same way you merge any branch.

The commands

Run these from the main checkout. The examples put worktrees in a folder next to the repository, named after it, so they stay out of the main checkout's file tree.

# A new branch in a new folder, starting from the current commit
git worktree add -b fix-login ../myapp-worktrees/fix-login

# Or start the branch from somewhere else, such as origin/main
git worktree add -b fix-login ../myapp-worktrees/fix-login origin/main

# See every worktree and the branch in each
git worktree list

# Start an agent in the new worktree
cd ../myapp-worktrees/fix-login
claude

Start a second agent in a second worktree the same way. Each one only sees its own folder.

Bring the work back

The agent commits on its branch. From the main checkout, merge that branch, or push it and open a pull request.

# In the main checkout
git merge fix-login

# Or share it for review
git push -u origin fix-login

Clean up

Remove the worktree when the branch is merged. Git refuses to remove a worktree with modified or untracked files unless you add --force, so check what is left first.

git worktree remove ../myapp-worktrees/fix-login
git branch -d fix-login

# If you deleted a worktree folder by hand, clear git's record of it
git worktree prune

Things that catch people out

1. Dependencies are per folder. node_modules, virtual environments and build output are not tracked, so a new worktree starts without them. Install them in each worktree before the agent runs tests.
2. Ignored files do not come along. A .env file or local config in the main checkout is not in the new worktree. Copy what the agent needs.
3. One branch, one worktree. If git worktree add says a branch "is already used by worktree", another worktree holds it. Use a new branch name.
4. Ports collide. Two worktrees that each start a dev server on the same port will clash. Give each one its own port.
5. Agents can wander. An agent can cd into another folder and edit there. Check where it worked before you merge.

Worktrees in Skiff

Skiff is a desktop app for Linux and macOS that runs coding agents side by side. File › New worktree… runs git worktree add -b for you and puts the folder at <repo>-worktrees/<branch>, next to the repository. Skiff lists every worktree git reports, including the ones you made yourself, and each agent session sits under the worktree it runs in.

Each worktree lists its changed files, and a double-click shows the diff. If an agent goes to work in another worktree, the sidebar shows it there too, which covers the last item in the list above.