How to run several Claude Code agents in parallel without losing track

To run several Claude Code agents in parallel, give each one its own git worktree so their edits never collide, then put every session's state somewhere you can see it at a glance. Anthropic's Claude Code best practices recommend parallel sessions "to speed up development, run isolated experiments, or start complex workflows." Setup is one flag. Most of this guide is about knowing which agent is waiting on you.

TL;DR

• claude --worktree <name> puts a session in a separate checkout under .claude/worktrees/, on a fresh branch.
• Git lets a branch live in only one worktree at a time, so no two agents can share a branch.
• claude agents (a research preview) lists your background sessions and flags the ones that need input.
• In a CHI 2008 study on interrupted work, interrupted people finished faster and reported more stress.
• Start with two or three agents.

What does running Claude Code agents in parallel mean?

It means several Claude Code sessions working on different tasks in one project at once, each in a separate copy of the code. One agent refactors auth while another fixes a flaky test.

Anthropic's best practices guide lists the options. Here they are, roughly by how much of the coordinating falls on you.

Approach	What it is	Who coordinates
Worktrees	Separate CLI sessions in isolated git checkouts	You
Desktop app	Several local sessions managed visually, optionally each in a worktree	You
Agent view	claude agents dispatches background sessions and shows them on one screen	You, from one screen
Subagents	Helpers inside one session, each with a separate context window	The main session
Agent teams	Experimental and off by default, with a team lead handing out shared tasks	Claude

Most people who say they run agents in parallel mean the first row, a few terminals with claude running in a worktree each. Start there. Agent teams are worth the setup only when the tasks really depend on each other.

How do you set up parallel Claude Code sessions with worktrees?

A git worktree is a second checkout of the same repository on a separate branch, sharing one history. Pass --worktree with a name, once per agent. The Claude Code worktrees docs say each one lands under .claude/worktrees/<name>/ on a new branch called worktree-<name>, and edits in one session never touch files in another.

1. Run claude once in the repository to accept workspace trust. The repo also needs at least one commit.
2. Add .claude/worktrees/ to your .gitignore, or the checkouts show up as untracked files.
3. List the gitignored files agents need, such as .env, in a .worktreeinclude file. Without it they're missing, because a worktree starts as a fresh checkout.
4. Open one terminal per task. claude --worktree auth-refactor goes in the first and claude --worktree flaky-test in the next.
5. Have each agent install dependencies before real work starts.
6. Exit when you're done. Claude deletes a clean, unnamed worktree by itself and asks first if one still holds work.

Git also refuses to check out one branch in two worktrees. Its worktree documentation describes several working trees attached to one repository, and git worktree add stops if another worktree already has the branch. The Codex worktree guide puts it bluntly, "Git only allows a branch to be checked out in one place at a time." So give every agent a branch and merge through pull requests.

How do you know which agent needs you?

You need one place that shows the state of all your sessions. The expensive moment is an agent sitting blocked on an approval while you're reading a different terminal.

Claude Code ships one answer, agent view. Run claude agents and you get "one screen for all your background sessions: what's running, what needs your input, and what's done." It's still a research preview and only covers background sessions, so an open session has to be sent there with /bg.

Oddly, the agent you forget is usually the one that finished first. It goes quiet, and quiet looks exactly like working.

Codex has separate signals. Its advanced configuration offers tui.notifications, which you can filter to event types like approval-requested.

Things get messy when you mix tools. Say Claude Code runs in three terminals and Codex in a fourth, with a Claude Cowork task in the desktop app. Each tool only reports on its own sessions. We built SupaYatta for exactly that setup. It lives in your notch and watches every Claude Code, Claude Cowork and Codex session, across every app and subscription.

• Finished turns show the first lines of what the agent said, with one click back into that exact session.
• When a session is blocked on an approval, a question or an error, a hand goes up. The count turns yellow, a chime plays and the screen edge glows until you look.
• Every session is listed newest first. Turns you haven't opened keep a red dot.

SupaYatta reads session status from the Claude Code and Codex hooks on your Mac. No account, no API key and no server of ours, and nothing about your sessions leaves the machine.

How many Claude Code agents should you run at once?

Start with two or three. How fast you can review what comes back sets the ceiling, and most people hit it long before they run out of terminals.

Each extra agent adds another stream of finished turns and approval prompts. In Mark, Gudith and Klocke's study of interrupted work, interrupted people completed tasks in less time but reported more stress, frustration, time pressure and effort. Checking six terminals by hand runs that experiment on you all day.

Two habits make more agents worth it.

1. Give each agent a check it can run. The best practices guide says Claude stops "when the work looks done," and without a test or build "you become the verification loop." With tests to run, the agent can fix its failures before it comes to you.
2. Pair a writer with a reviewer. A fresh session reviews the diff without the bias of having written it, then the first session works through the feedback.

Once you're regularly clearing reviews before the next agent finishes, try a fourth.

What are the limits and tradeoffs of parallel agents?

Merge conflicts and usage limits bite first, and setup cost catches people on big repos.

• Overlapping tasks still collide at merge time. Worktrees keep edits apart while agents work, but two agents changing the same module leave you a painful merge. Split work by area of the code, or run those tasks one after another.
• Usage goes faster. Four busy agents on one subscription eat its allowance roughly four times as fast as one. Check what's left before a big batch and put the most important task in the first session.
• Setup repeats per worktree. Because each one is a fresh checkout, the worktrees docs point out it needs its own dependencies and env files. On a large monorepo that can take longer than the task, so use subagents for small, read-heavy jobs.

This guide sticks to sessions on your own machine. Claude Code in the cloud runs sessions on Anthropic-managed infrastructure, per the best practices guide, and they're tracked there.

SupaYatta has limits too. It tells you when an agent finishes or needs you, and it never answers, approves or resumes anything for you. You'll need macOS 13 or later.

FAQ

Can Claude Code run multiple agents at the same time?

Yes, and it can start them for you. Run /batch with an instruction and Claude splits the change across 5 to 30 subagents, each in a separate worktree, according to Anthropic's best practices guide. It suits large migrations better than everyday feature work.

What is the difference between subagents and parallel sessions in Claude Code?

You drive a parallel session yourself, as a full conversation. Claude starts a subagent inside a session for a bounded job, and it reports a summary back. Adding isolation: worktree to a custom subagent's frontmatter gives each run a temporary worktree too, per the worktrees docs.

Are Claude Code agent teams ready to use?

They're experimental and off by default, so keep them for side projects for now. If your sessions need to share findings, Anthropic's guide lists cross-session messaging as a lighter option for sessions you run yourself.

Do parallel agents work with Codex too?

Yes. Codex's docs say worktrees "let Codex run multiple independent chats in the same project without interfering with each other." The CLI's notify setting can also run a program of your choice whenever a turn completes.

If you already run two agents, add the worktree flag to both today, then put every session in your notch with SupaYatta so the next blocked approval finds you.