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

Short answer

To run multiple Claude Code agents in parallel, give each session its own git worktree so they never write to the same files, then keep track of which session owns which branch and PR. For two sessions, claude --worktree <name> in two terminal tabs is enough. Past three or four, isolation is no longer the hard part; tracking is: ports, .env files, node_modules, failing CI and which branch already merged. Orchestrator.inc (formerly Agent Orchestrator) handles that tracking with a worktree per session, setup hooks, a Kanban board and CI routing. This guide shows the manual way first, then the Orchestrator way.

The manual way

1. Terminal tabs or tmux

The simplest setup is one terminal per session. With tmux you can name windows so you find them again:

tmux new-session -d -s agents
tmux new-window -t agents -n auth
tmux new-window -t agents -n billing
tmux attach -t agents

Do not point two sessions at the same checkout. Two agents editing the same file at the same time will overwrite each other's work. Worktrees fix this.

2. Create a worktree per session

A git worktree is a second working directory attached to the same repository, on its own branch:

cd ~/code/web
git worktree add ../web-auth -b feature/auth
git worktree add ../web-billing -b feature/billing
cd ../web-auth && claude

In the second tmux window:

cd ~/code/web-billing && claude

Each session now has its own files and branch. When a branch merges, remove its worktree:

git worktree remove ../web-auth
git branch -d feature/auth
git worktree prune

3. Let Claude Code create the worktree

Recent Claude Code releases include a --worktree flag that does the same thing for you, as of October 2026. It creates the worktree under .claude/worktrees/<name>/ on a branch named worktree-<name>, based on the remote default branch:

claude --worktree auth
claude -w billing

A .worktreeinclude file lists gitignored files to copy into each worktree, which is how you bring .env across. Clean worktrees are removed on exit; dirty ones prompt you first. The claude agents view lists background sessions in one TUI grouped by status.

Claude Code also has an experimental agent teams feature, enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Teammates share the main session's checkout rather than getting their own worktree, and split panes need tmux or iTerm2.

4. Handle ports, env files and dependencies

Most of the friction after the second session is environmental, not about git:

• Ports. Your dev server runs on one port, and the second worktree's dev server tries the same one. Give each session its own PORT and tell the agent which one it owns.
• Empty checkouts. A fresh worktree has no .env and no node_modules, so the first build fails and the agent spends context working out why. Copy .env with .worktreeinclude or a script, and either install dependencies per worktree or symlink node_modules from the main checkout if your toolchain tolerates it.
• Disk. Every full install per worktree costs disk space. Symlinking or a shared package cache keeps that down.

5. Keep track of branches, rebases and CI

These are the problems that grow with the number of sessions:

• Losing track. Several terminals look identical, worktree directories pile up, and it gets hard to remember which branches merged. Keep a short list of session, branch and PR, or name tmux windows after the issue.
• Rebase churn. Each time one branch merges into main, the others may need a rebase. Nothing tells the other sessions, so check before you push.
• CI and review. A red check or a review comment lives on GitHub. You find it, copy it, and paste it into the right terminal. Running gh pr checks in each worktree helps, but you still carry the result to the agent.

With two or three sessions this is manageable. Past that, the relay work takes over.

Comparing the approaches

Tips

• Give each session one issue. Sessions that touch unrelated files rarely conflict.
• Symlink node_modules rather than reinstalling, where your toolchain allows it.
• Decide each session's port before you start any dev server.
• Use Chat for sessions you check often and Terminal when you want Claude Code's native UI; you can switch later.
• Keep the machine awake, or move the work off it. Local orchestration needs the desktop running for automations and the mobile app; the Stay Awake setting handles that, and mobile access keeps working with a MacBook lid closed. To keep agents working with your laptop off, run sessions on a remote host or on Orchestrator Cloud.
• Add a reviewer from a different vendor per project with autoReview.

Doing this with Orchestrator.inc

Orchestrator.inc is an Apache-2.0 desktop app for macOS, Windows and Linux, free to run on your own machines, that runs Claude Code, and 37 other harnesses, in a worktree per session and tracks each session's PR (quickstart).

1. Install and add the project

Download the app, open it, and add your repository as a project. Orchestrator runs a local daemon on 127.0.0.1 and keeps its data under ~/.ao. No account is needed to run it locally. Optional Orchestrator Cloud plans start at $20/month (Pro $40/month, Enterprise on request) for agents that keep working while your laptop is closed.

To run sessions on a server or cloud VM instead, install Orchestrator's host there and add it in Settings under Remote hosts. You then start and supervise sessions on it from your desktop, with several hosts in one app. Machines linked to the same Orchestrator account find each other; otherwise they pair over an HTTPS tunnel or the LAN.

2. Configure the worktree once

In the project settings, add postCreate commands and symlinks so every new worktree is ready to build. Symlinking node_modules and .env from the main checkout avoids the empty-checkout problem and the disk cost (worktree workspace docs). Use environment variables for values every session needs. Ports are still per session: tell each agent which port to use in its prompt, then open that address in the session's browser with ao preview <url>.

3. Spawn sessions

From the desktop, click New session on the project, pick Claude Code, and choose Chat or Terminal. From the CLI, ao spawn does the same.

Each session gets its own worktree and branch. With issue intake turned on, you can start a session from a GitHub or GitLab issue; Orchestrator only reads issues and never comments on or moves them. Claude Code sessions can switch between Chat and the native terminal UI without losing their worktree.

4. Watch the board, not the terminals

The Kanban places sessions in Working, Needs you, In review and Ready to merge, based on session, PR, CI and review facts. Nothing is set by hand, so a session waiting on your answer shows up in Needs you instead of hiding in a terminal tab.

5. Let CI and review come to the session

When a session pushes, Orchestrator discovers its PR and polls GitHub or GitLab with ETags, with no webhooks or GitHub App. Failing checks are sent to the owning session with names, links and the end of the failed job's log, review comments arrive as focused feedback, and a merge conflict is sent to the session too, all de-duplicated (review loop guide). You can also have a Codex reviewer check the Claude Code PR and send its findings to the worker. When the card reaches Ready to merge, click Merge. Merge is always your explicit action.

6. Clean up

ao session cleanup --dry-run

The dry run lists what cleanup would remove, and cleanup skips any worktree with uncommitted changes, so nothing unsaved is lost.

To try it on real issues, follow the parallel issues guide with two Claude Code sessions.

Frequently Asked Questions

How do I run multiple Claude Code agents in parallel?

Give each Claude Code session its own git worktree, either with git worktree add or with the claude --worktree flag, and run each one in its own terminal or tmux window. Then keep track of which session owns which branch, port and PR. A supervisor such as Orchestrator.inc can create the worktrees and track the PRs for you.

Can I run multiple Claude Code sessions in the same directory?

You can, but you should not. Two sessions editing the same file at the same time overwrite each other's changes, which is why a worktree per session is the standard recommendation.

Does claude --worktree share node_modules between worktrees?

No. A worktree is a fresh checkout. The .worktreeinclude file copies gitignored files such as .env, but not installed packages, so you install dependencies in each worktree or link them yourself. Orchestrator.inc's symlinks setting links the installed packages folder from the main checkout into every new worktree.

How many Claude Code agents can I run at once?

There is no fixed cap on independent sessions. The real limits are your plan's usage, your machine and your attention. Tracking sessions by hand gets hard past two or three, which is the problem a board solves.

Does this work on Windows?

Yes. Claude Code runs on Windows, and Orchestrator.inc ships a Windows x64 desktop app with a native ConPTY terminal host, so you need neither WSL nor tmux. Agent teams split panes rely on tmux or iTerm2, so on Windows a board is the practical way to watch several sessions. You can download Orchestrator.inc from orchestrator.inc and follow the parallel issues guide on docs.orchestrator.inc to try it.