How to Set Up Git Worktrees for Parallel AI Agent Development

Running a single AI coding agent is powerful. Running three of them simultaneously on different features of the same codebase is transformative. But there is a catch: if you point multiple agents at the same git checkout, you will spend more time resolving conflicts than writing code. The solution is git worktrees -- an underused feature of git that gives each agent its own isolated working directory while sharing a single repository.

This guide walks you through setting up git worktrees specifically for parallel AI agent development. Whether you are running Claude Code, Codex, Gemini CLI, or any combination of tools, worktrees let you parallelize safely and merge cleanly.

What Are Git Worktrees and Why Do They Matter for AI Development?

A git worktree is an additional working directory linked to a single git repository. Unlike cloning the repo multiple times (which duplicates the entire .git directory and history), worktrees share the underlying object store. Each worktree gets its own branch, its own working copy of the files, and its own index -- but they all reference the same repository.

For AI-assisted development, worktrees solve the fundamental problem of concurrent access. When you launch Claude Code in one worktree and Codex in another, they each have their own filesystem sandbox. They can write files, run tests, and make commits without stepping on each other. When both are done, you merge the branches just like any normal git workflow.

Prerequisites and Initial Setup

Before diving into worktrees, make sure your environment is ready. You need git 2.15 or later (run git --version to check), a repository with at least one commit, and enough disk space for the working copies (though they are much lighter than full clones).

Start from your main repository checkout. For this guide, we will use a project called my-app as an example:

The git worktree list command shows all linked worktrees. Right now it should only show one entry -- your main working directory. That is about to change.

Creating Worktrees for Each AI Agent

The pattern is straightforward: for each agent you want to run in parallel, create a dedicated worktree on a new feature branch. The syntax is git worktree add <path> -b <branch-name>.

Here is a real-world setup where you want three agents working simultaneously -- one on a new API endpoint, one on UI components, and one on test coverage:

After running these commands, your filesystem looks like this:

• ~/Projects/my-app/ -- main checkout (stays on main branch)
• ~/Projects/my-app-api/ -- worktree for API agent
• ~/Projects/my-app-ui/ -- worktree for UI agent
• ~/Projects/my-app-tests/ -- worktree for test agent

Each directory is a fully functional working copy. You can cd into any of them, run your build tools, start dev servers, and -- most importantly -- point an AI agent at them.

Launching AI Agents in Each Worktree

With worktrees in place, launch your agents. The key principle: each agent gets its own terminal session pointed at its own worktree directory.

"The biggest mistake developers make with parallel agents is running them in the same directory. Worktrees are the simplest way to give each agent its own sandbox without duplicating your entire repo."

If you are using Claude Code, open a terminal in each worktree directory and start a session. Claude Code will automatically detect the git context and work within that branch. The same applies to Codex, Gemini CLI, or any other terminal-based AI agent.

All three agents are now working simultaneously. Because each one is in its own directory on its own branch, there are zero file conflicts during execution. Each agent can create files, modify imports, run builds, and commit changes independently.

Avoiding Conflicts: Branch Strategy for Parallel Agents

Worktrees eliminate filesystem conflicts, but you still need to think about merge conflicts when bringing branches together. The best strategy is to assign each agent to a different area of the codebase.

Here are the principles that keep parallel agent branches mergeable:

1. Minimize file overlap: If two agents both need to modify the same file (like a router config or an index file), designate one agent as the owner of that file and have the other reference it without modifying it.
2. Use additive patterns: Adding new files rarely causes conflicts. Modifying existing files sometimes does. Prefer tasks where agents create new modules, components, or test files rather than heavily refactoring shared code.
3. Base all branches on the same commit: When you create worktrees, they branch from your current HEAD. This gives each agent the same starting point, which minimizes divergence.
4. Merge frequently: If agents are working on related features, merge the first completed branch into main, then rebase the remaining branches before they finish. This keeps the merge surface small.

Monitoring and Managing Active Worktrees

Once your agents are running, you need visibility into what is happening across all worktrees. Git provides built-in commands for this, but you can enhance the workflow with a few techniques.

Check the status of all worktrees at any time with git worktree list. This shows each worktree path, the commit it is on, and which branch it is checked out to. Run it from any of the linked directories -- it always shows the full picture.

For real-time monitoring, use a tool like Beam that supports split panes and multiple terminal sessions. With Beam, you can have all three agent terminals visible simultaneously, watching their output side by side. The tab and project system lets you group related worktrees together, so you can switch between your "parallel agents" project and other work without losing context.

"Visibility is the key to parallel agent orchestration. If you cannot see what each agent is doing in real time, you are flying blind. A split-pane terminal environment transforms parallel development from chaotic to manageable."

Merging Completed Work Back to Main

When an agent finishes its task, you have a branch with commits ready to merge. Here is the recommended merge workflow:

The rebase step in item 5 is important. When you merge the first branch into main, the other agents' branches are now behind. Rebasing them onto the updated main ensures they incorporate the latest changes before they finish their work. If an agent is still actively running, wait until it completes its current task before rebasing.

Cleaning Up Worktrees

After merging, remove worktrees you no longer need. This keeps your filesystem clean and avoids confusion:

• git worktree remove ../my-app-api -- removes the worktree directory and unlinks it from the repository
• git branch -d feature/api-endpoint -- deletes the merged branch
• git worktree prune -- cleans up any stale worktree references if directories were manually deleted

Run git worktree list after cleanup to confirm only your main checkout remains.

Advanced: Worktree Templates and Automation

If you regularly use parallel agents, create a shell script that automates worktree creation. Here is a pattern that works well for teams:

Another advanced pattern is using worktrees for different stages of the same feature. Create one worktree for the implementation agent and another for a review agent. The implementation agent writes code, commits it, and the review agent (in its own worktree on a branch tracking the implementation branch) reviews the changes, suggests improvements, and creates a summary. This pipeline pattern turns worktrees into a multi-stage assembly line.

Tool Integration: Making Worktrees Work with Your Stack

Different AI agents and development tools have varying levels of worktree awareness. Here is what you need to know:

• Claude Code: Fully worktree-aware. It detects the git context of whatever directory you launch it in. Claude Code even has a built-in worktree command that automates creation and cleanup.
• VS Code / Cursor: Open each worktree as a separate window. The git extension correctly tracks the branch for each worktree directory.
• Node.js projects: Each worktree needs its own node_modules. Run npm install in each worktree after creation. Consider using pnpm with a shared store to save disk space.
• Docker: If your project uses Docker, each worktree can share the same Docker daemon but may need distinct container names. Use the worktree directory name as a container prefix.
• Database migrations: Be careful with agents that run migrations. Use separate test databases for each worktree to avoid migration conflicts.

"The best tool integration is the one you do not have to think about. Set up your worktrees correctly once, install dependencies, and let the agents treat each worktree as if it were the only copy of the project."

Real-World Example: Three Agents, One Sprint

Here is a concrete example from a real project. The goal was to complete three sprint items in one afternoon using parallel agents:

1. Agent 1 (Claude Code): Implement a webhook handler for Stripe payment events. Created in ../app-webhooks worktree. Took 18 minutes. Created 4 new files, modified 2 existing files.
2. Agent 2 (Claude Code): Add email notification templates for order confirmations. Created in ../app-emails worktree. Took 12 minutes. Created 6 new template files and a helper module.
3. Agent 3 (Codex): Write end-to-end tests for the checkout flow. Created in ../app-e2e worktree. Took 25 minutes. Created 3 test files and a test fixture.

Total elapsed time: 25 minutes (the longest agent). Total work completed: 3 sprint items that would have taken a solo developer most of a day. Merge conflicts: zero, because each agent worked on distinct parts of the codebase.

Troubleshooting Common Issues

Bringing It All Together

Git worktrees are the foundation of efficient parallel AI agent development. They solve the fundamental problem of multiple agents needing simultaneous access to the same codebase without creating filesystem conflicts or requiring heavyweight repository duplication.

The workflow is simple: create worktrees, assign agents, monitor progress, merge results, clean up. With practice, this becomes as natural as branching itself. The payoff is enormous -- you can parallelize development across multiple features, reduce wall-clock time for sprint work, and let each agent operate in a clean, isolated environment.

Pair this approach with a workspace tool like Beam that gives you split panes and project management, and you have a true parallel development cockpit. Each agent gets its own pane, each worktree gets its own tab, and you can see everything happening across your codebase in real time.