Git worktrees for parallel AI agents

Git worktree parallel development is the cleanest way to run several pieces of work in one repository without mixing them up. With AI agents it matters even more: if two agents work in the same folder, one overwrites the other’s changes, tests run against half-finished code and nobody can tell which change belongs to whom.

This post explains what git worktrees are, how to use them with agents, and how to keep every agent turn reversible.

What is a git worktree?

A git worktree opens a different branch of the same repository in a separate folder, at the same time. Each folder has its own working files, but the .git data is shared. A commit made in one worktree is visible from the others right away.

Compared with a clone:

Basic commands

Create a worktree on a new branch:

git worktree add ../acme-web-auth -b auth-refactor

Open a worktree from an existing branch:

git worktree add ../acme-web-billing billing-v2

List and remove worktrees:

git worktree list
git worktree remove ../acme-web-auth
git worktree prune

prune cleans up records of worktrees whose folders were deleted by hand.

Git worktree parallel development: one tree per agent

The rule for parallel agents is simple: give every agent at risk of conflicts its own worktree.

An example layout:

Tester shares Architect’s worktree because it tests Architect’s change and works only under tests/. The frontend agent works on something else entirely, on its own branch.

What this buys you:

• Agents never see each other’s half-written files.
• Each piece of work merges through its own branch and pull request.
• Dropping a piece of work is as easy as deleting its branch.

Managing worktrees in AgentVera

You can manage worktrees from the command line, but it gets hard to follow as agents multiply. In AgentVera, the Worktrees tab in the right panel lets you:

1. Create a worktree from a new or existing branch.
2. See each worktree’s change count, how far ahead or behind the main branch it is, and its last commit.
3. Start an agent directly in a worktree.
4. Lock, prune, force-remove a worktree and delete its branch.

When you create a new agent you can also pick a worktree as its workspace, and the agent’s pane shows its branch in a small tag. Markdown files agents change in worktrees are listed in the Specs panel as plans and docs.

Keep every turn reversible

Worktrees separate agents from each other. But what if an agent heads the wrong way inside its own worktree?

The traditional answer is to commit often, but committing every agent step clutters history. AgentVera’s turns take another route:

• At the start of every turn, a snapshot of the working folder goes to a hidden git ref.
• Your branch, index and stash are untouched.
• The last 60 turns are kept per agent.
• From Turns in the pane’s Options menu, you see the files a turn changed.
• Undo this turn reverts that turn’s changes, and you can undo the undo too.

So you can let an agent try things freely: if you don’t like the result, you’re one click from the previous state.

Before you merge

Before bringing finished work from parallel branches into the main branch:

• Run the tests in each worktree.
• Review the diffs; automatic code review speeds this up.
• Tidy commit messages. AgentVera’s Git panel can write a message in your repo’s style from the staged diff with Claude Haiku.
• Push the branch and open a pull request; the GitHub card in the Git panel shows the current branch’s pull request or opens a new one.

Common mistakes

• Opening the same branch in two worktrees. Git won’t allow it, and that’s a safeguard.
• Leaving records of deleted folders. Clean them with git worktree prune.
• Forgetting node_modules. Each worktree needs its own dependencies installed.
• Treating agent turns as commits. Turns are for undo; still commit for lasting history.

A sample day: three agents, two branches

Let’s make this concrete with a working day.

Morning: setup

The main folder has main checked out. There are two jobs: an auth restructuring and a settings page. You open two worktrees:

git worktree add ../acme-web-auth -b auth-refactor
git worktree add ../acme-web-settings -b settings-ui

Install dependencies in each:

cd ../acme-web-auth && pnpm install
cd ../acme-web-settings && pnpm install

Architect and Tester start in the auth-refactor worktree; the frontend agent starts in settings-ui.

Midday: a turn goes wrong

While editing the settings page, the frontend agent also changes the styling of a shared component. That’s out of scope. In the Turns list you see the files the last turn changed, undo the turn and tell the agent not to touch the shared component. The branch history stays clean, because undoing isn’t a commit; it’s a return to the snapshot on the hidden ref.

Evening: merging

When the auth work is done, you run the tests, check the review and push the branch. If the settings page isn’t finished, its worktree stays open and the agent continues in the same folder the next day. When you quit and reopen the app, AgentVera brings Claude and Codex agents back to the same conversation from the CLI history.

Environment details to watch in worktrees

The most common snags with parallel worktrees are about the environment, not the code:

• Port clashes: if you run a dev server in two worktrees at once, don’t let both ask for the same port. Give them different ports through environment variables.
• Env files: files that aren’t in git, like .env, don’t appear in a new worktree by themselves; copy them.
• Database: if two branches carry different migrations, sharing one local database can cause trouble.

AgentVera’s Ports panel shows listening ports and which agent started each, so you can track which worktree opened which server.

Copying an agent and forking the conversation

Sometimes you want to try the same problem two ways. When you copy an agent in AgentVera, its tool, account, model, effort, role, group and worktree are copied exactly, and you can fork the conversation history too (--fork-session for Claude, fork for Codex).

Combined with worktrees, that gives you a strong experiment setup: run two agents forked from the same conversation in two worktrees, compare the results and merge the branch you like. Deleting the other branch cleans up the experiment without a trace.

Checklist

• Does every agent at risk of conflicts have its own worktree?
• Are dependencies installed in each worktree?
• Do the agents’ roles say which folders they work in?
• Were tests and a review done before merging?

Wrapping up

Git worktree parallel development keeps agents physically apart, and turns keep each agent’s own changes reversible. Together they’re the foundation for working safely with several agents.

AgentVera puts worktrees, turns and the Git panel in one window. Read it alongside parallel coding agents, or start on the free plan.