How to use git worktrees to run AI coding agents in parallel

To run AI coding agents in parallel without them overwriting each other, give each agent its own git worktree: a separate working directory on its own branch that shares one repository. Create it with git worktree add -b, start the agent (Claude Code, Codex, Gemini CLI or any other) inside it, merge the branch when the work is done and remove the worktree. In MAO, a layer is such a worktree, created from the navigator and landed with a check first.

What is a git worktree?#

A worktree is an extra working directory attached to the same repository, with its own checked-out branch.

Git's own documentation describes it this way: a repository can support multiple working trees, so you can check out more than one branch at a time. The checkout that git clone or git init made is the main worktree; each one you add is a linked worktree. A linked worktree shares everything with the repository except per-worktree files such as HEAD and the index.

In practice that means each worktree has its own files, its own branch and its own staged changes, while commits, branches and the object store are shared. A commit made in one worktree is visible from every other worktree at once, with no push or fetch.

Why do parallel coding agents need separate worktrees?#

Because agents in one checkout edit the same files and share one branch.

When two agents work in the same directory, one agent's half-finished change is the other agent's starting point, a test run picks up edits neither agent meant to combine, and a git switch in one terminal changes the files under every agent. With one worktree per agent, each agent edits its own copy of the files on its own branch, and you decide what to combine by merging branches.

How do I set up one worktree per agent?#

Add one worktree and one new branch per agent from your main checkout, then start each agent in its own folder.

1. 1From the main checkout, create a worktree and a new branch for each agent. The path is where the folder goes; a sibling of the repository keeps it out of your project's files.
2. 2Copy in the ignored files the project needs to run, such as .env, and install dependencies in each worktree.
3. 3Start one agent in each worktree, in its own terminal.
4. 4Check what exists at any time with git worktree list.

git worktree add ../myapp-api -b agent/api
git worktree add ../myapp-tests -b agent/tests

cp .env ../myapp-api/
cp .env ../myapp-tests/

cd ../myapp-api && claude      # agent 1
cd ../myapp-tests && claude    # agent 2

git worktree list

git worktree list prints the main worktree first, then each linked one, with the commit and branch it has checked out:

/home/me/myapp        d3d2dd1 [main]
/home/me/myapp-api    d3d2dd1 [agent/api]
/home/me/myapp-tests  d3d2dd1 [agent/tests]

For scripts, git worktree list --porcelain gives a format that Git keeps stable across versions. To give an agent a branch that already exists, leave out -b: git worktree add ../myapp-fix fix/login.

How do I merge an agent's work back and clean up?#

Merge the agent's branch from the main checkout, then remove the worktree and delete the branch.

1. 1Have the agent commit its work on its branch.
2. 2In the main checkout, merge the branch as you would any other.
3. 3Remove the worktree. Git only removes a clean worktree: one with no untracked files and no changes to tracked files.
4. 4Delete the merged branch. Git refuses to delete a branch while a worktree has it checked out, so remove the worktree first.

cd ../myapp
git merge agent/api
git merge agent/tests

git worktree remove ../myapp-api
git worktree remove ../myapp-tests
git branch -d agent/api agent/tests

If git worktree remove refuses because the worktree has modified or untracked files, commit or move what you want to keep, or add --force to discard it. If a worktree folder was deleted by hand instead, git worktree list marks it prunable, and git worktree prune removes the leftover records (git worktree prune -n shows what it would remove).

What goes wrong with worktrees?#

Most problems come from branches that are already checked out, files Git does not track, and things the worktrees still share.

• The same branch cannot be checked out twice. git worktree add refuses a branch that another worktree already has, and so does git switch inside a worktree. That includes main while your main checkout is on it, so merge from the main checkout instead of switching a worktree to main. Give every agent a new branch with -b.
• Ignored and untracked files are not copied. A new worktree contains only the files Git tracks. .env, node_modules, build output and local config stay in the checkout they were created in, so copy or reinstall them in each worktree.
• Ignored files are removed without asking. Only modified or untracked files stop git worktree remove. A worktree that holds an ignored .env you copied in is removed along with it (tested with Git 2.56.0).
• Ports collide. Each worktree is a full copy of the project, so starting the dev server in two of them starts two servers. If both listen on the same fixed port, the second one fails. Give each worktree its own port, for example in its own .env.
• Deleting the folder leaves records behind. Removing a worktree directory with rm leaves its records in the repository until git worktree prune runs or Git expires them. Use git worktree remove instead.
• Submodules are not fully supported. Git's documentation calls multiple checkouts experimental, says submodule support is incomplete and does not recommend multiple checkouts of a superproject. A worktree with submodules needs --force to be removed.

Does Claude Code create worktrees itself?#

Yes. Its worktree flag creates the worktree and the branch and starts the session inside it.

According to Claude Code's documentation, claude --worktree feature-auth (or -w) creates a worktree under .claude/worktrees/feature-auth/ at the repository root, on a new branch named worktree-feature-auth. Run it again with another name in a second terminal for a second isolated session. A few details from the same page:

• New worktrees branch from the repository's default branch unless the worktree.baseRef setting is "head".
• A .worktreeinclude file at the project root, in .gitignore syntax, copies matching gitignored files such as .env into each new worktree.
• When you exit, a clean worktree from an unnamed session is removed with its branch; a worktree with changes or commits prompts you to keep or remove it.
• A custom subagent with isolation: worktree in its frontmatter always runs in its own temporary worktree.

The docs also suggest adding .claude/worktrees/ to your .gitignore so those worktrees do not appear as untracked files in the main checkout.

Which is better: one checkout, worktrees, clones or MAO layers?#

Worktrees and layers give each agent its own files while sharing one repository; clones isolate more but need push and fetch to share work.

How do MAO's layers use worktrees?#

A layer in MAO is a Git worktree on its own branch with its own canvas, created, switched and landed from the navigator.

1. 1Create. Choose New layer in the navigator's layer rail and enter a layer name and a branch name. You can copy Ground's layout as a starting point; copied nodes start as drafts, and permission-bypass launch options are not copied.
2. 2Work. Switch to the layer in the rail and place agents on it. Switching changes the active canvas and worktree; it does not merge anything. The layer's canvas is kept in MAO's own state, not as a file in the worktree, so it does not show up in git status.
3. 3Report. An agent on the layer can post where its work stands with mao layer status. A layer marked blocked or review is flagged as needing attention.
4. 4Land. Switch to Ground and choose Land… in the layer's menu. MAO checks for conflicts and uncommitted changes and shows the destination branch before it merges or fast-forwards. It never resets a branch, forces a change or stashes your work, and refuses if a branch moved since the check.
5. 5Archive. A landed layer is archived unless you turn on Keep the layer. Archiving is reversible; there is no command that deletes a layer.

From its terminal, an agent posts its layer's status. An agent marked as the Orchestrator can also create, land, archive and restore layers, and place new agents on a layer:

mao layer status --state review --progress 3/5
mao layer land "api"
mao layer archive "api"
mao layer restore "api"

Frequently asked questions#

Sources#

• git-worktree documentation: main and linked worktrees and what they share, add -b, the refusal to check out a branch twice, list and --porcelain, remove and --force, prune, and the note on submodules.
• git-clone documentation: a clone is a new repository with remote-tracking branches for the original.
• Claude Code: run parallel sessions with worktrees: --worktree, .claude/worktrees/, the worktree- branch name, worktree.baseRef, .worktreeinclude, cleanup on exit and isolation: worktree for subagents.
• Create a worktree layer: New layer, layer and branch names, copying the Ground layout.
• Land a layer into Ground: the checks before landing, Keep the layer, archiving after landing.
• Set a layer status, Switch between layers and Archive and restore a layer: status states, switching without merging, archive and restore.
• MAO 0.8.0 release notes: the dry run before landing, no resets, forces or stashes, and Orchestrators managing layers.
• MAO 0.5.20 release notes: a layer's canvas is kept in MAO's state, not in the worktree.
• The commands on this page were run in a test repository with Git 2.56.0 on Linux.

Checked on 2026-10-28.