Guide

How to Run Parallel AI Agents with Git Worktrees

Name: Fleet
Author: Fleet

The main problem with running multiple AI coding agents in the same Git working directory is that they collide. Agent A checks out a branch, agent B does the same, and both end up working on whatever branch the repository last landed on. Git worktrees solve this by giving each agent its own isolated checkout of the repository on disk without cloning the whole repo again.

This guide shows how to combine Fleet's multi-agent setup with Git worktrees so that parallel developer agents each have a dedicated working directory and can work on separate branches simultaneously.

Before you start

Git 2.5 or later (worktree support)
Fleet initialized in your primary repository clone
At least two developer agents defined in `.fleet/config.yaml`
Enough disk space for multiple working tree checkouts

1

Create a worktree for each agent

Use git worktree add to create an isolated checkout for each developer agent. Place worktrees as sibling directories to your main repo. Each worktree can be on its own branch, or you can let the agent create the branch once it starts.

# From your main repo directory
git worktree add ../repo-backend feature/backend-pagination
git worktree add ../repo-frontend feature/frontend-redesign

# Verify
git worktree list

2

Configure the worktree per agent

Set the worktree field on each agent in .fleet/config.yaml to point to its dedicated checkout. Fleet sets the FLEET_WORKDIR environment variable in the agent's tmux session. The agent uses this as its working directory for all file operations and Git commands.

agents:
  - name: backend-dev
    role: backend-developer
    department: engineering
    reports_to: tech-lead
    worktree: /path/to/repo-backend
  - name: frontend-dev
    role: frontend-developer
    department: engineering
    reports_to: tech-lead
    worktree: /path/to/repo-frontend

3

Start agents pointing at their worktrees

Launch both agents with fleet agent start --all. Each agent will open its tmux session with the working directory set to its worktree. Changes each agent makes are isolated to that worktree's branch.

fleet agent start --all
fleet status

4

Assign tasks to each agent

Use fleet task assign to give each agent its specific task. Since each agent is in its own worktree, they can both be actively modifying files, running tests, and committing without interfering with each other.

fleet task assign backend-dev "Add cursor-based pagination to GET /api/posts"
fleet task assign frontend-dev "Replace the sidebar navigation with the new design system components"

5

Clean up worktrees when branches merge

Once a branch is merged and no longer needed, remove the worktree to free disk space. The agent's tmux session should be stopped first.

fleet agent stop backend-dev
git worktree remove ../repo-backend
# If the worktree has untracked files, force-remove:
git worktree remove --force ../repo-backend

Common pitfalls

A worktree and the main clone share the same `.git` directory internally. Operations that lock the Git index (like a rebase in the main clone) can block commits in a worktree. Avoid running index-locking operations in the main clone while agents are active in worktrees.
Worktree branches must be unique. You cannot check out the same branch in two worktrees at the same time. Fleet does not enforce this — you will get a Git error at checkout time.
If you delete a worktree directory manually without running `git worktree remove`, Git tracks it as a stale worktree. Run `git worktree prune` to clean up stale entries.
Each worktree requires a full copy of the working tree files (though not the Git history). For large repositories, this can consume significant disk space across many worktrees.

When Fleet is the right tool

Git worktrees with Fleet make sense when you have two or more independent features that can be developed simultaneously and you want to run an AI agent on each one. This is particularly valuable in repositories where each feature takes hours or days of agent runtime. If your features share significant code and will conflict at merge time regardless, parallelism will not help much — the merge cost is deferred, not eliminated.

Frequently asked questions

Do I need one Fleet config per worktree?

No. Fleet config lives in the main repository at `.fleet/config.yaml`. Agents defined there can each point to different worktrees via the `worktree` field. You manage everything from one config file.

Can the reviewer agent review PRs from worktree branches?

Yes. The reviewer agent uses the GitHub CLI to fetch the PR diff remotely, so it does not need to be in the same worktree as the developer. The reviewer can run from the main clone or any worktree.

Run your first agent fleet

One binary. Five minutes. See every agent, coordinate every handoff, and keep a full audit trail of what your fleet did.

See how it works Install Fleet