How to Run Claude Code Agents in Parallel

Claude Code parallel agents let you run three, four, or five instances simultaneously, each on a separate branch, each executing an independent task at the same time.

The key mechanism is git worktrees. Each agent gets its own isolated working directory, so they never conflict. This guide covers the setup, the best use cases, and the coordination patterns that make parallel runs work in practice.

Key Takeaways

• Parallel agents require git worktrees: Each Claude Code instance needs its own working directory to avoid file conflicts, using isolated branch checkouts.
• Parallelism works for independent tasks only: Tasks that share files or depend on each other's output gain nothing from parallel execution.
• Launching is simple; coordination is the real work: Running claude -p in multiple terminals is easy, but splitting work cleanly and merging results is the real design challenge.
• Three to five agents is the practical sweet spot: Beyond five, merge complexity and API rate limits create overhead that outweighs speed gains.
• Parallel testing is one of the highest-ROI use cases: Running the same test suite against different environments simultaneously cuts testing time proportionally.
• Merge strategy must be planned before agents start: Deciding how to merge after agents complete creates bottlenecks that eliminate the time saved.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What Are Claude Code Parallel Agents and How Do They Work?

Claude Code parallel agents are multiple instances running simultaneously, each in its own isolated working directory on a separate branch. They share git history and CLAUDE.md configuration but never touch each other's files.

Each agent operates independently. It reads and writes files only within its own worktree, with no knowledge of what the other agents are doing at the same time.

• Git worktrees provide the isolation: A worktree is an additional checkout of your repo on a separate branch, in a separate directory, sharing the same git history.
• File isolation prevents conflicts: Two Claude Code instances writing to the same file simultaneously produce corrupted state that neither agent can recover from.
• Shared configuration stays consistent: All agents read from the same root CLAUDE.md, so your project conventions apply across every parallel run.
• What agents do not share: Working directory, active branch, and any in-progress file edits are fully isolated per agent.
• Parallel agents fit within broader patterns: Understanding agentic workflow design helps you choose when parallelism is the right tool and when a different pattern fits better.

Understanding this isolation model is the foundation. Every setup and coordination decision follows from it.

How Do You Set Up Git Worktrees for Parallel Claude Code Agents?

Create a separate git worktree for each agent using git worktree add. Each worktree gets a unique directory and a unique branch. That is the complete setup requirement.

Prerequisites: a clean git repository on main or master, Claude Code installed and authenticated, and roughly 2x your repo's disk space since each worktree is a full working directory copy.

• Create each worktree with one command: git worktree add ../project-feature-a feature/a creates a new directory checked out to branch feature/a. Repeat for each agent.
• Keep worktree directories adjacent to the main repo: /project, /project-feature-a, /project-feature-b is the standard convention and keeps paths predictable.
• CLAUDE.md is shared by default: The root CLAUDE.md applies to all worktrees. Add a worktree-specific CLAUDE.md only when you need to override scope for one agent's task.
• Use the complete worktree reference for edge cases: A full walkthrough for setting up git worktrees covers detached HEAD states, branch tracking, and cleanup procedures.
• Clean up worktrees after each run: git worktree remove ../project-feature-a removes the directory. git worktree prune clears stale references. Build this into your workflow.

Worktree setup takes about five minutes. The task scoping decisions you make before running agents are what actually determine whether the parallel run succeeds.

How Do You Launch Multiple Claude Code Instances Simultaneously?

Open a separate terminal session for each worktree, navigate into the worktree directory, and run claude -p "task description". Each agent runs headlessly and independently from that point.

The basic pattern is one terminal per agent. You can also script the launch if you are running the same parallel pattern repeatedly across sprints.

• The -p flag is what makes parallelism work: Using the headless mode flag runs each agent non-interactively, allowing multiple instances simultaneously without a human at each terminal.
• Shell scripting the launch: claude -p "task A" --output-dir /logs/agent-a & claude -p "task B" --output-dir /logs/agent-b & wait launches both agents and waits for both to complete.
• Direct each agent's output to a separate log file: Mixing output from multiple agents in one terminal makes it impossible to trace what each agent did.
• There is no unified progress dashboard: Monitor progress by checking individual log files or terminal sessions, which is a current limitation of the base setup.
• Rate limits apply across all simultaneous agents: Check your Anthropic plan's rate limits before running more than three agents simultaneously to avoid mid-run throttling.

Once your agents are running, your next task is planning how to review and merge their output. That coordination layer is where most parallel setups either save or lose the time they gained.

What Are the Best Use Cases for Running Claude Code in Parallel?

The highest-value parallel agent use cases share one property: each task produces a clean, independently mergeable output with no shared files. Testing, independent features, module refactoring, and documentation all fit this pattern.

Parallel agents produce the biggest gains when the work is genuinely partitionable. Here is what that looks like in practice.

• Parallel feature development: Assign each agent one independent sprint feature. Agent A handles authentication, Agent B handles notifications, Agent C handles export, with no shared files and all running simultaneously.
• Parallel test environment runs: Run the same test suite against multiple configurations at once: different Node.js versions, different database backends, different OS environments.
• Parallel module refactoring: Large codebases with separated modules (payments, notifications, users) can refactor in parallel, one agent per module on its own branch.
• Parallel CI/CD pipeline runs: One agent handles linting, one handles security scanning, one handles test generation, all running simultaneously rather than sequentially.
• Parallel documentation generation: One agent per service or module generating API docs, README updates, or changelog entries. This is high-volume, low-dependency work.
• Larger workload coordination: For teams managing more complex parallel setups, Claude Dispatch for agent orchestration provides a coordination layer above individual agent launches.

If you are unsure whether a task fits the parallel pattern, apply the dependency test: can each unit of work complete correctly without knowing what the other units are doing? Yes means parallel agents are safe to use.

When Should You Use Parallel Agents vs Subagents?

Use parallel agents when you have multiple complete, independent tasks to run simultaneously. Use subagents when one complex task has internal parts that can be parallelised but share a common goal and output.

The distinction comes down to whether the work is truly separate or just internally decomposable.

• Parallel agents are task-level parallelism: Each agent has a self-contained goal, its own branch, and produces a mergeable output. Best when you have a list of unrelated tasks.
• Subagents are subtask-level parallelism: An orchestrator Claude Code instance spawns subagents to handle components of one larger task. Full patterns at subagent orchestration.
• The dependency test decides which to use: Can each unit complete correctly without knowing what the other units are doing? Yes means parallel agents. No means subagents.
• The merge test also applies: Does each unit produce a clean, mergeable branch? Yes means parallel agents are safe. No means the orchestrator pattern handles synthesis better.
• When neither pattern fits: Tasks that share state, write to the same files, or require real-time coordination need to be broken into genuinely independent pieces before parallelism applies.

The dependency test and the merge test together cover the vast majority of decisions. Apply both before launching any parallel run.

How Do You Coordinate and Merge Results from Parallel Agents?

Plan your merge strategy before launching agents. The three options are sequential PR merge, integration branch, or automated merge tooling. Choosing after agents complete creates the bottleneck that eliminates the speed you gained.

Coordination is the section most parallel agent guides skip. It is also where most parallel runs lose their time savings.

• Sequential PR merge: Each agent's branch is reviewed and merged one at a time. Easiest to manage, but review is not simultaneous, making it best for small teams or strict review requirements.
• Integration branch: All agent branches merge into a shared integration branch first, then integration is reviewed once. Faster to review, but requires resolving cross-agent conflicts in one place.
• Automated merge tooling: Scripts or CI handle non-conflicting merges automatically, flagging only true conflicts for human review. Highest setup cost, highest throughput for recurring parallel runs.
• Conflict risk scales with task scoping quality: Agents working on truly independent files rarely conflict. Agents touching shared utilities or config files conflict predictably, so identify shared files before launching.
• Post-run review checklist: Confirm each agent hit its completion condition, all tests pass on each branch, and no files were modified outside the intended directory scope.

Human review before merging to main is still required. Parallel agents accelerate the development work, not the code review step, so build the review time into your workflow estimate.

Conclusion

Parallel agents multiply Claude Code's throughput directly. Three agents on three independent tasks complete in the time one agent takes for one task. In practice, you capture 60 to 80 percent of that theoretical maximum after accounting for merge and review time.

The git worktree setup takes five minutes. Task scoping is the real work. Agents working on genuinely independent files in isolated worktrees run fast and merge cleanly. Agents working on poorly scoped tasks that touch shared files create conflicts that cost more time to resolve than the parallelism saved.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Ready to Scale Your Development Workflow with Parallel Agents?

Setting up parallel agents is straightforward. Designing the task decomposition, worktree structure, and merge strategy so they consistently save time rather than create coordination overhead is the harder problem.

At LowCode Agency, we are a strategic product team, not a dev shop. We design and build AI-powered development workflows, including parallel Claude Code configurations that fit your team's sprint structure, codebase architecture, and review process.

• Task decomposition design: We analyse your sprint backlog and identify which work partitions cleanly for parallel execution without cross-agent dependencies.
• Worktree configuration: We set up the directory structure, branch naming conventions, and CLAUDE.md configuration for your specific repository layout.
• Launch automation: We build the shell scripts or CI configuration that launches your parallel agents consistently without manual terminal management.
• Merge strategy selection: We select and configure the right merge approach for your team size, review process, and conflict risk profile.
• Rate limit planning: We assess your Anthropic plan limits against your parallel agent count and recommend the right configuration to avoid mid-run throttling.
• AI agent development: We build custom agent workflows that go beyond the base Claude Code setup when your use case requires more coordination than parallel agents provide.
• Full product team: Strategy, architecture, development, and QA from a team that treats your developer workflow as a product worth getting right.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want your parallel agent workflow designed and running correctly from day one, talk to our team.