How to run multiple Claude Code agents in parallel (2026 guide)

One Claude Code session is a pair programmer. Five sessions are closer to a small team, and a team needs a way to split the work so people don’t get in each other’s way.

Claude Code now has built-in tools for most of this. Worktrees keep sessions out of each other’s files. Agent view shows every background session on one screen. Agent teams let one session manage the others. This guide covers each of them, when to use which, and the one thing none of them handle: deciding what each session should work on next, across sessions, machines and days.

The short version:

1. Give every session its own checkout with claude --worktree <name>.
2. Run sessions in the background and watch them with claude agents.
3. Use agent teams when one session should split up and assign the work, and /batch for one large mechanical change.
4. Keep the backlog outside any single session, on a board agents can claim work from over MCP, and start sessions straight from its cards.

Step 1: give each session its own worktree

The first thing that goes wrong with parallel agents is files. Two sessions in the same directory will edit the same files, run each other’s half-finished tests and commit each other’s changes.

A git worktree fixes that: a second working directory with its own branch, sharing the same repository history. Claude Code creates one for you:

claude --worktree feature-auth

That creates .claude/worktrees/feature-auth/ on a new branch called worktree-feature-auth and starts Claude there. Run the same command with a different name in another terminal for a second isolated session. -w is the short form, and leaving out the name gets you a generated one.

A few things worth setting up once:

• Ignore the folder. Add .claude/worktrees/ to .gitignore so worktrees don’t show up as untracked files in your main checkout.
• Copy your env files. A worktree is a fresh checkout, so gitignored files like .env aren’t there. List them in a .worktreeinclude file at the project root (same syntax as .gitignore) and Claude Code copies them into every new worktree.
• Install dependencies. Each worktree needs its own node_modules or virtualenv. Ask Claude to set it up, or add it to your project’s setup script.
• Start from a pull request. claude --worktree "#1234" fetches that PR and creates the worktree from it, which is useful for review and follow-up fixes.

When you exit, Claude removes a clean worktree automatically and asks before removing one that has changes. Subagents can be isolated the same way: add isolation: worktree to a custom subagent’s frontmatter and each run gets its own temporary checkout.

Worktrees are the foundation for everything else here. Without them, parallel sessions will break each other’s work.

Step 2: run sessions in the background with agent view

Once you have more than two or three terminals open, switching between them becomes the bottleneck. Agent view puts every background session on one screen:

claude agents

Sessions are grouped by state: Ready for review (a pull request is open), Needs input (Claude is waiting on an answer, a permission or your next prompt), Working and Completed. You can peek at a session with Space, attach with Enter and detach with the left arrow while it keeps running. From your shell you can start one without opening the view:

claude --bg "fix the flaky login test"

A session you dispatch this way moves into its own worktree before it edits files, so step 1 is taken care of.

Agent view is in research preview, and the sessions run on your machine: they survive sleep but stop if the machine shuts down.

Step 3: let Claude coordinate with agent teams

With worktrees and agent view, you do the coordinating: you decide which task goes to which session. Agent teams hand that job to Claude. One session becomes the lead, spawns teammates, and puts work on a shared task list that teammates claim from.

Agent teams are experimental and off by default. Turn them on in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then describe the team you want:

Spawn three teammates to build the export feature: one on the API endpoint,
one on the React screen, one writing integration tests. Each owns its own files.

Tasks can depend on each other, and claiming uses file locking so two teammates can’t grab the same task. Teammates can message each other directly, and you can talk to any of them.

A few things to know before you rely on it:

• Teammates don’t get worktrees. Split the work so each teammate owns different files, or they’ll overwrite each other.
• One team per session. The team belongs to the lead’s session. You can’t share it with another session, a second machine or a colleague.
• Resuming is limited. /resume doesn’t bring back in-process teammates.
• Costs grow with the team. Each teammate is a full Claude instance with its own context. Anthropic suggests starting with three to five.

Agent teams are good for research, review, and features that split cleanly across layers. They’re more than you need for a list of unrelated tasks.

For one big change: /batch

If the parallel work is really one change spread over many files (a rename, a migration, a new lint rule), /batch splits it across 5 to 30 subagents, each in its own worktree. It’s a packaged combination of subagents and worktrees, and it’s the quickest option for that kind of job.

Headless: claude -p

Everything above assumes you’re watching. For scripts and CI, claude -p "<prompt>" runs one task non-interactively and exits, and claude -p --worktree isolates it. Set up permissions carefully first: a headless session can’t stop and ask you anything, so whatever it isn’t allowed to do simply fails.

Which approach to use

Worktrees isolate files, not work

Worktrees make sure two sessions never edit the same file. They don’t stop two sessions doing the same task, and they don’t make sure someone is doing the task that matters most.

Look at what each tool knows. Agent view knows your sessions, not your backlog. An agent team’s task list belongs to one lead session on one machine. Claude Code’s own task list is tied to the session it was made in. None of them answers the questions that matter once you run agents every day:

• What’s queued up for the next free session?
• Which sessions are waiting on me, across every machine?
• What got shipped yesterday, and by which agent?
• Can a teammate see any of this?

That backlog needs to live outside any single session, somewhere every session can read from and claim work on, with claims that can’t collide.

Give parallel sessions one shared queue over MCP

This is what Yokka is for. You plan the work as cards on a board, and each Claude Code session connects over MCP and pulls from it. Connect once, at user scope, so every worktree and background session has it:

claude mcp add --transport http --scope user yokka https://api.yokka.ai/mcp/c/<token>

Then start as many sessions as you like, each with the same instruction:

claude -w agent-1 "Pick up the next card on the Yokka board and ship it"
claude -w agent-2 "Pick up the next card on the Yokka board and ship it"

Each session runs the same loop:

1. get_next_card finds the top card waiting in Ready.
2. claim_card claims it. A card is held by one agent at a time, and the claim is refused if another active agent already holds it, so two sessions never end up on the same card. The card moves to Working with that session’s name on it.
3. set_checklist and report_progress show its plan and progress on the card, live.
4. request_input asks you a question when it’s stuck. The card moves to Needs you and is flagged, so you can see at a glance which of your sessions need an answer.
5. complete_card finishes with a one-line summary and a link to the pull request from its worktree branch.

You can send sessions to different swimlanes (“take the next card in Bugs”), and you can mix clients: a Codex session and a Cursor agent can work from the same board. If a session goes quiet for 30 minutes, its card is flagged so it doesn’t sit in Working forever. The agent loop walks through every call.

A few lines in CLAUDE.md keep every session consistent:

## Work queue
- Work comes from the Yokka board. Claim a card before you change any code.
- One card per session. Open a PR from your worktree branch, then complete the card with its link.
- If you need a decision from me, use request_input and wait. Don't guess.
- If you find something out of scope, file it with add_card instead of fixing it.

Skip the terminals: start sessions from the card

Opening a terminal per session works, but you’re still the one starting every session. Yokka’s runner does that part for you. It’s a small, open-source companion you install once on the computer that holds your code:

npx yokka-runner

Map each project to its folder and choose how runs work: in place, one at a time in your folder, or a git worktree per run, so several cards run in parallel, each on its own branch (like yokka/yk-12-add-checkout). You set how many runs go at once. Then press Start on a card, from the board or your phone, and the runner starts Claude Code (or Codex) on that computer to work it.

What you get over starting sessions by hand:

• Start from anywhere. Line up cards on your phone and press Start. The sessions run at your desk.
• Sessions you can still open. Claude Code runs as a background session with Remote Control, so it appears in the Claude desktop app and updates live. Pick it up there if you want to take over.
• Answer from your phone, steer from the card. When an agent asks something or hits a permission prompt, your phone gets a push. Tap it and you answer in the agent’s own session: the Claude app for Claude Code, or the Codex app after Continue in Codex on the card hands the thread over. Pause, resume or stop a run from the card.
• A record per card. When a run ends, the card shows the branch, how many commits it made and how many files it left uncommitted.
• Your machine stays yours. The runner only connects outward, keeps folder paths in its local config, and can only be asked to start a run for a card. Runs never skip permissions: they start in the permission mode you picked. Only you can start runs on your runner: no teammate, not even an admin.

Runners come with Pro and up. The runner docs cover setting one up.

Practical limits

Running agents in parallel speeds things up, but some limits don’t go away:

• Usage multiplies. Ten sessions use roughly ten times the quota of one. Watch your plan’s rate limits before scaling up.
• Conflicts move to merge time. Worktrees stop agents editing the same files at once, but two branches can still conflict when you merge. Size cards so they touch different parts of the codebase, and split swimlanes by area.
• Review becomes the bottleneck. Three agents can open PRs faster than you can review them. A WIP limit on Working warns you when too much is in flight (the count turns amber; it doesn’t block anything), and sending finished bugs to a Verify lane means you check each fix before it closes. We wrote more about this in Human-in-the-loop for AI coding agents.
• Disk and memory. Each worktree is a full checkout with its own dependencies. On a big monorepo, five of them add up.

FAQ

Can multiple Claude Code instances work on the same repo?

Yes. Give each one its own git worktree with claude --worktree <name> so they don’t edit the same files. They share the repository’s history and remotes, and each works on its own branch.

How many Claude Code agents can I run at once?

There’s no hard limit. In practice your plan’s rate limits, your machine and your ability to review the output limit you first. Three to five parallel sessions is a sensible starting point.

How do I keep track of all my Claude Code sessions?

On one machine, claude agents shows every background session and which ones need input. To track the work itself (what’s queued, who’s on what, what shipped) across machines and teammates, use a shared board that agents update over MCP.

Do Claude Code tasks persist across sessions?

Claude Code keeps its task lists on your machine, tied to a session or, for agent teams, to the lead session. For a backlog that outlives sessions, works across machines and that other people can see, keep it on an external board.

What’s the difference between agent teams and subagents?

Subagents do a side task inside one session and report back to it. Agent teams are separate sessions that share a task list and message each other, coordinated by a lead. Teams cost more tokens and are still experimental.

How do I clean up Claude Code worktrees?

Exiting a session removes a clean worktree automatically and asks about one with changes. For worktrees left behind by headless runs, use git worktree list and git worktree remove <path>.