Git Worktrees: Give Each Parallel Agent Its Own Workspace

If two coding agents work in the same project folder, they can easily interfere with one another: editing the same files, staging each other’s changes, or switching branches underneath an active task.

Git worktrees give you a cleaner arrangement. Each agent gets its own project folder and branch, while all of them share the same Git history. You can develop features in parallel, then review and combine them deliberately.

The Mental Model: One Repository, Several Checkouts

A Git repository stores your project’s version history. A working tree is the set of checked-out files you can open, edit, and run.

Normally, you interact with one working tree at a time. When you switch branches, Git updates the files in that folder to match the branch you selected.

A Git worktree lets you attach additional working trees to the same repository. Instead of repeatedly switching one folder between branches, you can keep several branches checked out in separate folders:

project/                  main worktree → main
project-auth/             agent A's worktree → feature/auth
project-search/           agent B's worktree → feature/search

Each folder contains a working copy of the project. Agent A can edit the authentication feature while agent B works on search, without either agent changing the other’s in-progress files.

Worktrees isolate editing state, not project history. Each agent gets its own workspace, but completed commits live in one shared repository.

Is a working tree different from the repository root?

In everyday use, repository root usually means the top-level folder of the working tree you are currently using.

So in the example above, there are three working-tree roots:

• project/ is the root of the main working tree.
• project-auth/ is the root of the authentication working tree.
• project-search/ is the root of the search working tree.

When you tell an agent to work in project-auth/, that folder is its repository root for file edits and commands. It is not a subfolder of project/; it is another checkout attached to the same repository.

The important distinction is between where the editable files are and where Git stores its underlying history and metadata.

What Is Separate—and What Is Shared?

To understand why worktrees suit parallel agents, it helps to separate Git’s editing machinery from its history.

Here is what those distinctions mean in practice.

Working files: each agent edits its own copy

Suppose the authentication agent edits:

project-auth/src/login.ts

That changes only the file in project-auth/. It does not change any corresponding file in project/ or project-search/.

The search agent can continue working without suddenly encountering half-finished authentication code.

The index: each agent stages its own changes

Git’s index, also called the staging area, holds the changes selected for the next commit. Running git add places a file’s current contents into that staging area.

Because each worktree has its own index, the authentication agent can stage changes without putting them into the search agent’s next commit.

Likewise, running git status in the search worktree does not show the authentication agent’s uncommitted edits.

HEAD: each worktree has its own current checkout

HEAD is Git’s name for the current checkout. Usually, it points to a branch name:

project/          HEAD → main
project-auth/     HEAD → feature/auth
project-search/   HEAD → feature/search

Each worktree has its own HEAD, so each can remain on a different branch.

The subtlety is that HEAD is private to the worktree, but the branch it points to is shared. There is one shared feature/auth branch reference, not a separate version of that branch for every folder.

For this reason, Git normally prevents you from checking out the same branch in two worktrees simultaneously. Give each active agent its own branch rather than trying to put every agent on main.

Commits: visible everywhere, applied only when you choose

When the authentication agent commits its changes, Git:

1. Stores the new commit in the shared repository.
2. Moves the shared feature/auth branch reference to that commit.
3. Leaves the other worktrees’ files unchanged.

From the search worktree, you can now inspect the authentication branch:

git log feature/auth

You do not need to push and fetch just to make that local commit visible to another worktree.

But visibility is not adoption. The search worktree stays on feature/search; its files do not automatically acquire the authentication changes. Combining branches is a separate, explicit operation.

What lives in .git?

In a typical original checkout, .git is a directory containing Git’s repository data.

In a linked worktree, .git is usually a small file pointing to worktree-specific metadata stored under the main repository’s .git directory. That metadata includes the linked worktree’s HEAD and index, while commit objects and ordinary branch references remain shared.

You rarely need to manage these internals yourself. They explain why a worktree is another checkout of the same repository—not a completely independent clone.

Set Up One Worktree per Agent

A straightforward workflow is to start both agents from the same clean, up-to-date base branch.

1. Prepare the base branch

From your original project folder:

cd project
git status
git switch main
git pull

Check git status first so you know whether you have uncommitted work to handle before switching branches or updating the base.

Here, main is the base branch: the starting version of the project from which you want the agents to develop their features.

2. Create a branch and worktree for each task

git worktree add -b feature/auth ../project-auth main
git worktree add -b feature/search ../project-search main
git worktree list

The first command means:

• git worktree add: create another working tree.
• -b feature/auth: create a new branch named feature/auth.
• ../project-auth: put its checked-out files in this sibling folder.
• main: start the new branch at the current commit on main.

The second command does the same for search. git worktree list shows the worktrees Git knows about, including their paths and checked-out branches.

3. Assign each agent a folder and a bounded task

Your assignment should make the workspace and branch explicit:

Work in ../project-auth on feature/auth. Implement the authentication task, run the relevant tests, and commit your changes on that branch.

Give the search agent its own corresponding instructions.

The useful unit is one agent, one worktree, one task branch. A bounded task also makes review easier: you know what each branch is supposed to contain.

Inside its assigned folder, an agent uses Git normally:

git status
git add src/login.ts
git commit -m "Implement authentication changes"

There is no special worktree-specific way to edit, stage, or commit.

Review and Integrate One Feature at a Time

Once an agent has finished and committed its work, return to your main worktree.

Before merging, review the branch’s changes and check its test results. Then integrate the branches one at a time:

cd project
git switch main
git merge feature/auth

A merge combines another branch’s changes into your current branch. After the first merge, run the relevant tests before proceeding:

git merge feature/search

Testing again after the second merge matters because two features can work independently yet fail when combined.

Worktrees do not eliminate merge conflicts

A merge conflict occurs when Git cannot automatically reconcile changes—for example, when both branches alter the same lines in different ways.

Worktrees prevent agents from overwriting one another’s unfinished files. They do not guarantee that the finished changes are compatible.

Even without a textual conflict, two features might make incompatible assumptions about an interface or shared behavior. Review and integration tests still matter.

Parallel development needs deliberate integration. Separate folders make simultaneous work safer; they do not replace checking how the results fit together.

Treat Each Worktree as Its Own Development Environment

Git separates the project files and staging state. It does not automatically isolate everything your application uses.

For each agent, consider whether you need separate:

• Dependencies: each folder may need its own dependency installation.
• Ports: two development servers cannot normally listen on the same local port at once.
• Databases: agents sharing one database can interfere through migrations or test data.
• Temporary files and output paths: tools writing to a shared location can still collide.

A useful rule is to ask: Does this resource live inside the agent’s worktree, or is it shared outside it?

Two worktrees can have perfectly separate source files while their running applications modify the same database. That isolation is an application and tooling concern, not something Git worktrees provide.

Clean Up When the Work Is Done

After the branches have been integrated and you no longer need the agent workspaces, remove them:

git worktree remove ../project-auth
git worktree remove ../project-search

Git normally requires a worktree to be clean before removing it, helping protect uncommitted work. If removal is refused, inspect the folder rather than immediately forcing deletion.

Removing a worktree does not delete its branch. Delete the integrated branches separately:

git branch -d feature/auth
git branch -d feature/search

The lowercase -d performs a safety check and normally refuses to delete a branch whose work has not been merged.

The Practical Takeaway

For parallel agents, Git worktrees provide a simple division of responsibility:

• Separate folders protect each agent’s in-progress edits.
• Separate indexes and HEADs keep staging and checkouts independent.
• Shared commits and branch names make completed work available across worktrees.
• Explicit merges let you review and combine features on your terms.

Start each agent on its own task branch, point it at its own worktree root, and integrate the results one at a time. You get parallel development without making every agent share the same live workspace.