Multiple agents in one project: working with Git worktree

Parallel work becomes awkward when two agents edit the same working folder. One is fixing a form, another is restructuring a component, and the tests run against a mixture of unfinished changes. Git worktree separates the files: each task gets its own folder and branch.

A worktree is an additional working copy of the same Git repository. History is shared, while the checked-out branch and working files are separate. This makes it possible to develop several changes at once. See the Git manual for the underlying model and commands.

• Git manual

Which tasks can run in parallel?

Start with two independent changes: one agent fixes a form's error handling, while another updates help text. If both need to change a data schema or shared component, agree on the interface first and complete the dependency in sequence.

Separate folders prevent unfinished files from mixing, but they do not resolve conflicting intentions. Two changes can merge cleanly in Git and still break the application together.

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 adjacent directory names must be unused.

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 also has its own worktree startup options; see its parallel sessions guide. The manual approach makes folders and branches visible independently of the client.

• 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 a documentation task with a separate constraint: leave the form code alone. These are teaching examples; use your project's actual paths, commands and acceptance criteria.

Check each copy's environment. Dependencies and personal configuration files may need separate setup. Two development servers need different ports. If both use the same test database, isolate their data or avoid running data-changing scenarios concurrently.

Accept the results

Review each diff independently. First assess whether it meets the brief, then examine the tests. Commit the reviewed changes on their respective branches.

Merge them one at a time into your chosen integration branch. After the second merge, test the combined user journey again. Passing checks on two separate branches does not prove they work together.

If conflicts appear, determine which behavior must be preserved. Do not ask an agent to accept every change from one side mechanically: that can discard 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 a force flag, Git refuses to remove an ordinary worktree with uncommitted changes. Do not add `--force` merely to silence that warning. Removing a worktree leaves its branch in place; decide what to do with the branch separately. Worktree commands.

• Worktree commands