Guide / Claude Code

How to run multiple Claude Code agents in parallel

To run multiple Claude Code agents in parallel without conflicts, give each agent its own working copy, its own task and a clear owner for every file. This guide compares git worktrees, subagents, agent teams and an external orchestrator, walks through a worktree setup, and shows how to coordinate the agents on a shared task board.

Claude Code features described as of November 2026. Official sources checked .

Options

Four ways to run Claude Code agents side by side

The right setup depends on two questions: do the agents edit files, and do they need to coordinate while they work? Most teams combine options, for example worktree sessions for implementation with a task board as the shared queue.

Git worktrees

Best for: Independent changes that each need their own branch and pull request.

Trade-off: You start, watch and review each session yourself.

Subagents

Best for: Focused side tasks inside one session, such as research, review or tests.

Trade-off: Built for bounded delegation: results return to the session that called them.

Agent teams

Best for: Work where teammates need to discuss findings and divide files while they work.

Trade-off: Experimental, one team per session, and in-process teammates are not restored on resume.

External orchestrator

Best for: Work that spans sessions, days or people, with dependencies and a handoff record.

Trade-off: Agents need instructions and credentials to read and update the board.

Git worktrees. Claude Code can start a session in its own git worktree, so each session works on separate files and a separate branch while sharing the repository history. This is the simplest way to run several independent sessions at once.

Subagents. A subagent is a specialized assistant that the main session delegates to. Each subagent runs in its own context window with its own system prompt, tool access and permissions, and returns its result to the session that called it. A custom subagent can set isolation: worktree to work in a temporary worktree.

Agent teams. An experimental feature, disabled by default, where a lead session coordinates teammates. Each teammate is a separate Claude Code session with its own context window, and the team shares a task list. Read the Claude Code agent teams guide for setup and limits.

External orchestrator. A task board outside Claude Code holds the queue, owners, dependencies and history. Agents read and update it through an MCP server or API, so the plan survives when a session ends and humans can review the same record. The AI agent orchestration guide covers this model beyond coding agents.

Step by step

Set up parallel Claude Code sessions with git worktrees

  1. Split the work first. Write down each task, the files it owns and what done means. Two tasks that must edit the same file are not ready to run in parallel; do them in sequence or move the shared change into its own task.
  2. Start one session per task. Open a terminal for each task and pass a name to the worktree flag:

    Shell / one worktree per session

    # Terminal 1
    claude --worktree billing-export
    
    # Terminal 2
    claude --worktree audit-log-filters
    Claude Code creates the worktree under .claude/worktrees/<name>/ on a new branch named worktree-<name>. Running the command again with an existing name opens that worktree. Add .claude/worktrees/ to your .gitignore.
  3. Or create worktrees yourself. Plain git works the same way if you want to choose paths and branch names:

    Shell / manual git worktree

    git worktree add ../app-billing-export -b billing-export
    cd ../app-billing-export
    claude
    
    # After the branch is merged or abandoned
    git worktree remove ../app-billing-export
  4. Prepare each environment. A worktree is a fresh checkout. Install dependencies in each one. To copy gitignored local files such as environment variables into new Claude Code worktrees, list them in a .worktreeinclude file at the project root. It uses .gitignore syntax, and only files that match and are also gitignored are copied:

    .worktreeinclude

    .env
    .env.local
    Check that local services such as dev servers and test databases will not collide on the same ports when several sessions run checks at once.
  5. Give each session a standalone brief. Sessions do not share conversation history. Include the task, the files the session owns, files it must not touch, the checks to run and where to report.
  6. Review and clean up. Review each branch as its own pull request. When you exit an interactive session, Claude Code removes the worktree of an unnamed session automatically if nothing changed, and asks first for a named session or a worktree with changes. Non-interactive runs with -p are not cleaned up, so remove those worktrees yourself.

For side tasks inside a single session, a custom subagent can get its own temporary worktree. Save a file like this in .claude/agents/:

.claude/agents/bug-reproducer.md

---
name: bug-reproducer
description: Reproduces a reported bug with a failing test. Use for new bug reports.
isolation: worktree
---

Reproduce the bug described in the task with the smallest failing
test. Do not change implementation files. Report the test file, the
command you ran and the failure output.

Claude Code removes the subagent’s worktree automatically if the subagent makes no changes. By default an isolated worktree starts from the repository’s default branch, not from your uncommitted edits. If a subagent must see work in progress, set worktree.baseRef to "head" in your settings and commit the change first, or give the subagent the change explicitly.

Coordination

Use a task board as your Claude Code orchestrator

Worktrees keep files apart. They do not tell an agent which task to take next, stop two agents from taking the same task, or keep a record after the session closes. An external task board does that job. In Atoll, AI agents are members of the workspace alongside people, and they work from the same issues.

  • Agents as teammates. Create an Atoll agent member for each worker role. Issues are assigned to agents the same way they are assigned to people, and every status change and comment is attributed to the agent that made it.
  • Scoped access. An agent can be limited to specific projects, and its API keys and OAuth grants act with that agent’s permissions. One OAuth connection can authorize several agent profiles, so each session can act as a different agent.
  • A queue per agent. The heartbeat returns an agent’s assigned issues and the signals that need attention, such as blocked or stalled work. Dependencies mark an issue as blocked by other work, so an agent can see what is ready to start.
  • Next task from a parent. For a large change split into sub-issues, atoll_next_child returns the next open, unblocked child by priority. It only reads; it does not claim the issue, so assign it before an agent starts.

Connect Claude Code to the hosted Atoll MCP server. User scope makes the server available outside a single project directory, which helps when every worktree has its own path:

Shell / add the Atoll MCP server

claude mcp add --transport http --scope user atoll https://atollhq.com/mcp

Run /mcp in Claude Code to sign in with OAuth. On the Atoll consent page, select or create the agent profiles this connection may use. The Atoll MCP integration page covers other clients, and the Claude Code integration guide covers project-scoped setup and the Atoll skill. Then start each worktree session with a brief like this:

Example session prompt

Use the Atoll MCP server.
1. List the Atoll agent profiles and use the one named "worker-billing".
2. Read my heartbeat and pick the highest-priority assigned issue
   that is not blocked. If none is assigned, stop and tell me.
3. Move it to In Progress and comment with this worktree's branch name.
4. Do the work in this worktree only. Run the project's checks.
5. Comment with changed files, check results and open questions,
   then move the issue to review. Do not merge.

Ask each agent to post the branch name, changed files and check results as a comment. A reviewer can then follow every parallel thread from one board instead of reading several terminal transcripts. For the wider workflow, see project management for AI coding agents.

Pitfalls

Common failure modes in Claude Code multi-agent orchestration

Merge conflicts

Worktrees prevent agents from overwriting each other’s files while they work, but the branches still meet at merge time. Assign file ownership up front, keep shared files such as types, schemas and lockfiles with one task, and merge small branches often. When one branch lands, ask the other sessions to rebase before they continue.

Duplicated work

Two agents told to “pick something from the backlog” will often pick the same thing. Assign each task to exactly one agent, have the agent move it to In Progress before editing, and record dependencies so blocked work stays out of the queue.

Stale context

Each session only knows what it was told and what it reads. A decision made in one session does not reach another unless you record it. Put contract changes and decisions on the shared issue, have agents re-read the issue before they resume, and pull the latest main branch before a long task.

Review bottlenecks

Parallel agents produce work faster than one person can review it. Limit the number of open branches, require each agent to report the checks it ran, and keep every task small enough to review in one sitting.

FAQ

Claude Code agent orchestration FAQ

Can Claude Code run multiple agents at the same time?

Yes. You can start several Claude Code sessions, each in its own git worktree. Within one session, Claude can delegate to subagents, which run in their own context windows. Agent teams, an experimental feature, let a lead session coordinate separate teammate sessions. Choose by how much the workers need to talk to each other and whether they edit files.

What is a Claude Code orchestrator?

An orchestrator decides which work runs, who does it, and what counts as done. In Claude Code that can be the main session delegating to subagents, or the lead of an agent team. For work that spans days, several sessions or human reviewers, an external task board can act as the orchestrator: it holds the queue, the owner of each task, dependencies and the handoff record.

Do I need git worktrees to run Claude Code agents in parallel?

Only when more than one agent edits files. Two sessions in the same checkout share one working tree, so one agent can overwrite or build on the other’s unfinished changes. A worktree gives each session its own files and branch while sharing the same repository history. Read-only research or review sessions can share a checkout.

How many Claude Code agents should I run at once?

Start with two or three. Each session uses its own context window and usage, and every result still needs integration and review. Add another agent when the existing ones are waiting on you less than you are waiting on them, and when there is independent work with separate file ownership to give it.

How do parallel agents avoid picking the same task?

Give every task exactly one owner before work starts. On a shared board, assign the issue to one agent and have that agent move it to In Progress before it edits anything. Reading the next available task is not the same as claiming it, so an agent that only reads a queue can still collide with another reader.

Does Atoll start or run Claude Code sessions in this workflow?

No. In this workflow you start the Claude Code sessions yourself. Atoll holds the shared record: issues, assignees, dependencies, status and comments. Each session reads and updates that record through the Atoll MCP server, acting as the agent profile you authorized.

References

Official sources

Checked 17 November 2026. Claude Code changes often; compare these references with your installed version before adopting the workflow.

Connect Claude Code to Atoll

Give parallel agents one shared queue.

Assign work to agents and people on the same board, and keep every handoff in one place.