Parallel Agentic Development With Git Worktrees: A Practical Playbook

The Problem With Running One Agent at a Time

If you’ve used Claude Code for serious development work, you’ve probably hit the same wall: one agent, one terminal, one branch, one task at a time. You wait for the agent to finish the auth system before it can start on the API layer. You sit idle while it works through a refactor. The model is fast, but the workflow is sequential.

Parallel agentic development fixes that. By combining git worktrees with multiple Claude Code sessions, you can run several agents simultaneously — each working on a separate feature, each isolated in its own directory, none of them stepping on each other. This guide covers the five-pillar system that makes it work reliably in practice.

The primary keyword throughout this article is parallel agentic development — and by the end, you’ll have a concrete playbook for doing it without merge chaos.

What Git Worktrees Actually Are (and Why They Matter for AI)

Most developers know git branches. Fewer know git worktrees. The difference matters enormously when you’re running multiple agents.

A branch is a pointer to a commit history. You can only have one branch checked out at a time in a given directory. If you want to switch to another branch, you either stash your changes or commit them first.

A worktree is a separate working directory linked to the same git repository. You can have multiple worktrees, each with a different branch checked out, all at the same time. They share the same .git object store — no repo duplication — but each has its own working files.

For AI agents, this is significant. Each Claude Code session needs its own working directory. If two sessions share a directory and operate on the same files simultaneously, you get corruption: overwritten changes, confused context, broken builds. Worktrees eliminate the problem by giving each agent its own isolated filesystem path.

You can learn more about the mechanics in this overview of Claude Code git worktree support for parallel branches.

The basic commands:

# Create a new worktree for a feature branch
git worktree add ../project-feature-auth feature/auth

# List all active worktrees
git worktree list

# Remove a worktree when done
git worktree remove ../project-feature-auth

Each ../project-feature-auth directory is a full working copy of your repo, but on its own branch. Launch a Claude Code session pointed at that directory, and the agent has its own sandbox.

The Five-Pillar System for Parallel Agentic Development

Running two agents at once is easy. Running five agents on the same project without conflicts, context collisions, or wasted work — that takes a system. Here are the five pillars that hold it together.

Pillar 1: Isolated Worktree Setup

Every agent gets one worktree. No exceptions. The isolation has to be at the filesystem level, not just at the branch level.

The naming convention matters more than it seems. Use a consistent pattern so you can tell at a glance which worktree belongs to which task:

../myproject-feat-auth        # Agent 1: authentication
../myproject-feat-api         # Agent 2: REST API layer
../myproject-fix-db-perf      # Agent 3: database performance
../myproject-refactor-types   # Agent 4: TypeScript type cleanup

Each worktree also needs its own environment. If your project uses .env files, copy or symlink them appropriately. If you’re running a dev server inside the worktree, make sure ports don’t collide — assign distinct port numbers per agent.

Set up a small shell script to automate worktree creation. Something like:

#!/bin/bash
# create-worktree.sh
BRANCH=$1
TASK=$2
git worktree add "../$(basename $(pwd))-${TASK}" "${BRANCH}"
echo "Worktree created at ../$(basename $(pwd))-${TASK}"

This makes spinning up a new parallel session a one-liner.

Pillar 2: Task Decomposition Before You Start

The most common failure mode in parallel agentic work isn’t a technical problem — it’s a planning problem. You launch two agents on tasks that touch the same files. They both modify utils.ts. One overwrites the other’s work. Merge time becomes debugging time.

The fix is upfront decomposition. Before you create a single worktree, map out:

Which files does each task touch? If two tasks have overlapping file lists, they need to be sequential, not parallel.
What are the dependencies? Task B can’t start if it depends on output from Task A. Parallel only works on independent tasks.
What’s the integration point? Define upfront how and when each agent’s work gets merged back.

A simple table works well for this:

Task	Agent	Primary Files	Dependencies	Integration Point
Auth system	Agent 1	`src/auth/*`	None	PR after completion
API routes	Agent 2	`src/routes/*`	None	PR after completion
DB migrations	Agent 3	`migrations/*`	None	Sequential merge
Frontend forms	Agent 4	`src/components/forms/*`	Auth system	After Agent 1 merges

This planning step takes 10–15 minutes but saves hours of conflict resolution.

Claude Code’s split-and-merge pattern formalizes this decomposition further — it’s worth understanding before you scale to larger agent teams.

Pillar 3: Shared Context Without Shared State

Agents working in parallel need shared context but must not share state. The distinction is important.

Shared context means each agent understands the project goals, coding conventions, architecture decisions, and cross-cutting concerns. You want agents building consistent, compatible code.

Shared state means agents modifying the same files or objects simultaneously. This causes conflicts and breaks things.

The solution is a project brief — a markdown document checked into the repo that every agent reads at the start of its session. Include:

Project overview and architecture decisions
Coding conventions (naming, file structure, patterns to follow)
API contracts between components (e.g., the shape of data the auth system will expose)
List of tasks in progress and their owners
Known constraints (performance requirements, security rules, etc.)

Store this as AGENTS.md or PROJECT_BRIEF.md in the root of the repo. When you start a new agent session, your first instruction points the agent to this file.

Some teams also use a shared tasks.json — a structured task list that agents can read from but each writes to their own section. This gives you a lightweight coordination layer without agents overwriting each other. If you want to go deeper on real-time task sharing between agents, see how parallel agents share a task list.

Pillar 4: Integration and Merge Protocols

What happens when an agent finishes? If you don’t have a clear answer before the agents start, you’ll spend significant time untangling branches.

Define your integration protocol upfront. There are two main approaches:

Pull request per agent: Each agent’s worktree becomes a PR when the task is complete. You review, run CI, and merge. Clean, auditable, but slower if you have many agents completing simultaneously.

Orchestrated sequential merge: An orchestrator (human or another Claude session) monitors agent completion and merges branches in a defined order. Faster for large parallel runs, but requires more coordination infrastructure.

For most teams, the PR approach is right until you’re running more than four or five parallel agents regularly. At that scale, the operator pattern for running multiple AI agents in parallel terminals gives you more control.

Regardless of approach, establish these rules:

Each agent’s branch must pass linting and tests before merge is considered
Agents should not modify shared lock files (like package-lock.json) unless that’s explicitly their task
Database migrations need special handling — only one migration can run at a time on a given environment
API contracts defined in the project brief are frozen during parallel runs; changing them requires pausing parallel work

Pillar 5: Monitoring and Agent Coordination

When three agents are running simultaneously, you need visibility into what each one is doing without manually watching three terminals.

The minimum viable monitoring setup:

Named tmux or screen sessions per agent, so you can switch between them quickly
Log files — redirect each agent’s output to a dated log file so you can review history
Status checkpoints — instruct each agent to write a brief status update to a STATUS.md in its worktree every N steps (or at major milestones)

A more structured approach uses an orchestrator session — a Claude Code instance whose job is to coordinate the other agents, check their status, and handle blockers. This is sometimes called an AI command center. There’s a detailed walkthrough of building an AI command center for managing multiple Claude Code agents if you want to go that route.

For smaller parallel runs (two to three agents), simple tmux pane management is usually enough. You can glance at each panel, check progress, and intervene if an agent is stuck or has taken a wrong turn.

Step-by-Step Setup for Your First Parallel Run

Here’s a concrete walkthrough for getting three agents running in parallel.

Prerequisites

Git repo initialized and on a stable main branch
Claude Code installed and configured
tmux installed (or equivalent terminal multiplexer)
.env file ready for copying to worktrees

Step 1: Create the Project Brief

Write AGENTS.md in your repo root. Include architecture, conventions, and the specific tasks for this parallel run. Commit it to main.

Step 2: Decompose and Plan

Fill in the task table. Verify no file overlap between tasks. Confirm dependencies allow parallel execution.

Step 3: Create Worktrees

git checkout -b feat/user-auth
git checkout main
git worktree add ../myapp-auth feat/user-auth

git checkout -b feat/api-routes
git checkout main  
git worktree add ../myapp-api feat/api-routes

git checkout -b feat/email-service
git checkout main
git worktree add ../myapp-email feat/email-service

Copy environment files to each worktree as needed.

Step 4: Start tmux Sessions

tmux new-session -d -s auth -c ../myapp-auth
tmux new-session -d -s api -c ../myapp-api
tmux new-session -d -s email -c ../myapp-email

Step 5: Launch Claude Code in Each Session

Attach to each tmux session and start Claude Code with a task-specific prompt:

tmux attach -t auth
# In the auth session:
claude code
> Read AGENTS.md, then implement the user authentication system as described. 
> Focus only on src/auth/* files.

Repeat for each session with the appropriate task.

Step 6: Monitor and Intervene

Use tmux list-sessions to see all running sessions. Switch between them with tmux attach -t [session-name]. Check status files and logs. Handle any blockers or questions the agents raise.

Step 7: Integration

As agents complete, run their tests locally, review the diff, and merge via PR or your defined integration protocol.

For a deeper look at what this looks like when running multiple sessions across longer-running projects, see Claude Code parallel sessions for working on multiple projects simultaneously.

Common Mistakes (and How to Avoid Them)

Launching Agents Before Planning File Ownership

This is the most expensive mistake. Two agents modifying src/types/index.ts simultaneously will create a conflict that’s tedious to resolve and may require rerunning one of them. Always map file ownership before creating worktrees.

Forgetting to Isolate Node Modules

If your agents run npm install in their worktrees independently, they each get their own node_modules. That’s fine and expected. But if they share a symlinked node_modules, concurrent installs can corrupt the directory. Keep them isolated.

Context Drift Between Sessions

If an agent makes an architectural decision mid-task — say, it changes a data model shape — and doesn’t communicate that to the project brief, other agents may build against the old shape. Build a habit of updating AGENTS.md when any significant decision is made, and pausing parallel agents if the change affects their work.

No Exit Criteria for Agents

Agents without clear success conditions will either stop too early or keep going past the scope of their task. Define “done” in the initial prompt: what files should exist, what tests should pass, what behavior should be demonstrable.

Skipping Code Review Because It’s “Just AI Code”

AI-generated code still needs review. Setting up automated code review with multiple AI agents can catch common issues automatically, but human review remains important for architecture-level decisions and security-sensitive code. Don’t let the speed of parallel generation tempt you into skipping this.

Scaling Up: From Three Agents to Ten

Three parallel agents is the comfortable zone for most developers managing their own workflow. Getting to ten requires additional infrastructure.

Task Queuing

At scale, you need a task queue rather than a fixed set of tasks. As agents complete, they pull the next available task from the queue. This requires a shared task list with locking — otherwise two agents might claim the same task simultaneously.

A simple implementation uses a JSON file:

{
  "tasks": [
    {"id": "task-001", "status": "in_progress", "agent": "auth-session", "description": "..."},
    {"id": "task-002", "status": "pending", "agent": null, "description": "..."},
    {"id": "task-003", "status": "pending", "agent": null, "description": "..."}
  ]
}

Agents check the file, claim a pending task by writing their session ID, and update status when done. It’s low-tech but effective for moderate scale.

More sophisticated setups use a proper orchestrator — a Claude Code agent whose only job is managing the other agents. See how parallel agents coordinate in real time with Claude Code agent teams for a production-ready version of this pattern.

Headless Execution

At scale, you don’t want to manage ten tmux sessions manually. Claude Code’s headless mode lets you run agents without an interactive terminal, firing them off as background processes. This is what makes truly large-scale parallel runs possible without constant supervision. There’s a full breakdown of Claude Code headless mode for running agents autonomously.

Dependency-Aware Scheduling

As your task graph gets complex, you need scheduling that respects dependencies. Task C can’t start until Task A and B complete. Task D blocks on a database migration. A dependency-aware scheduler handles this automatically rather than requiring you to manually track it.

This is where purpose-built multi-agent architectures earn their complexity cost. For teams shipping at scale, the agentic workflow patterns from sequential to fully autonomous are worth understanding in full.

Where Remy Fits in This Picture

Parallel agentic development is powerful, but it has a fundamental constraint: the agents are working against a codebase, and the codebase is the source of truth. If the code is messy, the agents produce messy output. If the architecture is unclear, agents make inconsistent decisions. You spend significant effort writing project briefs, managing context, and cleaning up divergent choices.

Remy approaches this differently. The source of truth isn’t the code — it’s a spec, a structured markdown document that describes what the application does. The code is compiled from that spec.

When you’re building with Remy, context drift between agents is far less of a problem because every agent is working from the same spec. The spec defines data types, API contracts, validation rules, and edge cases with precision. Agents don’t have to guess at the architecture or make judgment calls about data shapes — those decisions are encoded in the spec itself.

And because Remy compiles a full-stack app — backend, database, auth, deployment — from the spec, you’re not orchestrating agents across three different layers of the stack. The compilation step handles the cross-layer consistency that parallel agentic development normally requires careful coordination to maintain.

If you’re spending significant effort on the coordination overhead described in this article — the project briefs, the file ownership maps, the merge protocols — it’s worth asking whether a spec-driven approach would reduce that overhead structurally rather than procedurally.

You can try Remy at mindstudio.ai/remy.

FAQ

What are git worktrees and why do they matter for parallel AI coding?

Git worktrees let you check out multiple branches of the same repository into separate directories simultaneously. For AI coding agents, this is essential because each agent session needs its own isolated filesystem. Without worktrees, two agents working in the same directory will overwrite each other’s changes, corrupt file state, and produce unreliable output. Worktrees give each agent its own sandbox while sharing the underlying git history. A detailed technical explanation is available in this guide to using git worktrees with Claude Code for parallel development.

How many parallel Claude Code sessions can you run at once?

There’s no hard technical limit. The practical constraints are your machine’s CPU and RAM, your API rate limits, and your ability to monitor and coordinate the agents effectively. Most developers run two to five agents in parallel without dedicated infrastructure. With tmux automation, headless execution, and an orchestrator agent, teams have run ten or more parallel sessions on large codebases. Start small — two or three agents — and scale up once you have the coordination patterns dialed in.

How do you prevent merge conflicts when running multiple agents in parallel?

Upfront task decomposition is the main tool. Before any agent starts, map which files each task touches and verify there’s no overlap. Assign explicit file ownership per agent. Tasks that share files must be sequenced, not parallelized. Beyond that, clear integration protocols (PRs, code review, ordered merges) catch anything that slips through the planning stage. The most common mistake is skipping the planning step and discovering conflicts during integration.

What’s the difference between parallel agents in the same session vs. separate worktrees?

Running parallel sub-agents within a single Claude Code session — sometimes called the split-and-merge pattern — is different from running separate Claude Code sessions in separate worktrees. Intra-session parallelism uses Claude’s native ability to spawn sub-agents, which share context and coordinate through the parent session. Cross-worktree parallelism uses separate, fully independent sessions. The former is better for tasks within a single bounded context; the latter is better for large, multi-feature development work where each task is genuinely independent.

Do you need special tooling to coordinate parallel agents?

No. The setup described in this article uses only git worktrees, tmux, and a shared project brief file — all standard tools. More elaborate setups add an orchestrator agent, a task queue file, and log aggregation, but these aren’t required to get started. The complexity you add should be proportional to the scale of your parallel work. Two or three agents in tmux panes is a perfectly valid production workflow.

How do you handle shared configuration and environment variables across worktrees?

Copy your .env file into each worktree directory. Don’t symlink it — if one agent modifies it, you don’t want that change reflected in other worktrees unexpectedly. If you need worktree-specific settings (like distinct port numbers for dev servers), create a .env.local override in each worktree. Keep your base .env in sync manually or with a simple script that copies it to all active worktrees when it changes in main.

Key Takeaways

Git worktrees give each AI agent an isolated working directory without duplicating the repository, which is the foundation of conflict-free parallel development.
The five-pillar system — isolated setup, task decomposition, shared context without shared state, integration protocols, and monitoring — covers the full lifecycle of a parallel run.
Upfront file ownership mapping is the single most important step. Skip it and you’ll pay for it during merge.
Scaling from three to ten agents requires queuing, headless execution, and dependency-aware scheduling — not just more worktrees.
The coordination overhead of parallel agentic development is real. Spec-driven development approaches like Remy address some of it structurally rather than procedurally.

If you’re looking for a way to build full-stack applications with less coordination overhead overall, try Remy at mindstudio.ai/remy.