Multiple agents in one project: working with Git worktree

Two agents editing the same working folder get in each other's way. One is fixing a form, the other is restructuring a component, and the tests run against a mixture of half-finished changes. Git worktree keeps the files apart by giving each task its own folder and its own branch.

A worktree is an additional working copy of the same Git repository. The copies share history, but each has its own checked-out branch and working files, so you can develop several changes at once. The Git manual covers the underlying model and the commands.

• Git manual

Which tasks can run in parallel?

Start with two independent changes. Say one agent fixes a form's error handling while another updates the help text. If both would have to touch the data schema or a shared component, agree on the interface first and do the dependent part in sequence.

Separate folders stop unfinished files from mixing. They do nothing about conflicting intentions: two changes can merge cleanly in Git and still break the application between them.

Create two working copies

This example assumes an existing repository with at least one commit. Run the commands from its main folder. The branch names and the sibling directory names must not exist yet.

git status --short
git worktree add -b ai/form-fix ../project-form HEAD
git worktree add -b ai/docs-update ../project-docs HEAD
git worktree list

Both copies start at the current HEAD commit. Uncommitted changes in the original folder are not carried over. If both tasks need them, prepare an agreed starting version first. Do not commit someone else's unfinished work just to follow this example.

In two separate terminals, enter the new directories and start your agent. For Claude Code:

cd ../project-form
claude

Open `../project-docs` in the second terminal. Claude Code can also create the working copy for you: `claude --worktree <name>` puts it under `.claude/worktrees/` inside the repository, and the parallel sessions guide has the details. The manual route has one advantage. The folders and branches are plain to see whichever client you use.

• parallel sessions guide

Brief each agent

Define the outcome and the boundaries. For the first agent:

Fix the form submission error message. Work in the current worktree. Find the form and its tests, and preserve successful submission. Do not change the API structure or documentation. Show the diff and check results. Do not merge branches.

Give the second agent the documentation task and one extra constraint: leave the form code alone. Both briefs are teaching examples, so swap in your project's actual paths, commands and acceptance criteria.

Check each copy's environment. Dependencies will probably need installing again, and personal configuration files that Git does not track (`.env`, for one) have to be copied across by hand. Two development servers need different ports. If both use the same test database, isolate their data or avoid running scenarios that change it at the same time.

Accept the results

Review each diff on its own. Check it against the brief first, then look at the test results. Commit what you have reviewed, each change on its own branch.

Merge the branches into your chosen integration branch one at a time. After the second merge, run through the combined user journey again, because green checks on two separate branches say nothing about how the changes behave together.

If conflicts appear, decide first which behavior has to survive. Do not ask an agent to accept every change from one side mechanically. That is an easy way to lose part of the other task.

Remove a worktree when finished

Confirm that the changes you need are saved and accepted, and that no unsaved files remain. Then, from the main working copy, run:

git worktree remove ../project-form
git worktree remove ../project-docs

Without `--force`, Git refuses to remove a worktree that still has uncommitted changes or untracked files. Do not add the flag just to make the error go away. Removing a worktree leaves its branch in place. What happens to the branch is a separate decision.

• Worktree commands