Parallel agents
How to run multiple Claude Code agents at once: four ways, easiest last
Updated November 17, 20268 min read
To run multiple Claude Code agents, you start several Claude Code sessions at the same time: in separate terminals, in tmux panes, in git worktrees with subagents or agent teams, or inside a manager app that watches them all. Each way below fixes a problem the one before it leaves open. Read the warning first, because it applies to all four.
Read this before you start a second agent
Watch out
Two agents working in the same project folder will overwrite each other's files. Neither one knows the other exists. Agent A saves its version of a file, agent B saves over it a minute later, and A's work is gone with no error message. Anthropic's agent teams docs say it plainly: two teammates editing the same file leads to overwrites. Give every agent either a different project or its own copy of the project.
Here is why people run multiple Claude Code instances. One session builds a feature while another fixes a bug, a third writes tests and a fourth works on a different project. You stop waiting on one agent and start reviewing finished work from several. Every method below still has to deal with the same problems: keeping agents out of each other's files, knowing which agent needs you, and the extra usage each agent burns.
The four ways are ordered from least setup to most protection. The first needs nothing at all. The last does the most work for you.
Way 1: multiple Claude Code agents in separate terminals
This is Claude Code in multiple terminals, the simplest way to run multiple Claude Code sessions. Open a terminal window or tab for each agent, move into a project folder, and start Claude. On Windows, Windows Terminal tabs work well. On a Mac, Terminal or iTerm2 tabs do the same job.
# Terminal tab 1
cd ~/projects/shop
claude
# Terminal tab 2
cd ~/projects/blog
claudeThat's it. Each claude is a full, separate session with its own memory of the chat. Use /rename inside each one to give it a name you will recognise later, so /resume can find it again tomorrow.
What goes wrong: this is only safe when each terminal works on a different project, as in the example. Point two tabs at the same folder and you hit the overwrite problem from the warning. The second problem is attention. Claude stops to ask permission, and unless you happen to be looking at that tab, it sits there. Most terminals give no signal by default. You can add a sound with hooks, as shown in Claude Code notifications, but every tab plays the same sound. Once you have more than a few tabs, it gets hard to tell which one is waiting.
Way 2: Claude Code split screen with tmux
tmux is a free terminal tool that splits one window into panes and keeps your sessions alive even if you close the window. It gives you a Claude Code split screen where you can see several agents working at once.
tmux new -s agents # start a tmux session called "agents"
# Ctrl+b then % split side by side
# Ctrl+b then " split top and bottom
# Ctrl+b then arrow key move between panes
# run claude in each pane
# Ctrl+b then d detach (agents keep running)
tmux attach -t agents # come back latertmux also powers the split-pane view of Claude Code agent teams (more on teams in Way 3). With teams turned on, add this to ~/.claude/settings.json and each teammate opens in its own tmux pane when you start Claude inside tmux:
{
"teammateMode": "auto"
}If you use the Claude desktop app instead, its split view does a simpler version of the same thing: Alt-click (Option-click on a Mac) a session in the sidebar to open it beside the current one. Full tmux setup is in Claude Code with tmux.
What goes wrong: tmux has a learning curve, and Anthropic notes it works best on macOS. On Windows it means running everything inside WSL. Splitting the screen also does nothing about file safety: four panes on one project folder still overwrite each other. Small panes make long diffs hard to read. And if Claude Code exits without tidying up, tmux sessions can linger. List them with tmux ls and close one with tmux kill-session -t <name>.
Way 3: git worktrees, subagents and agent teams
This is where the overwrite problem gets solved. A git worktree is a second working folder for the same project, on its own branch. Agents in different worktrees can't touch each other's files. When one finishes, you merge its branch back like any other git branch.
One worktree per session
Claude Code has worktrees built in. Each command below makes a new folder under .claude/worktrees/ on a new branch called worktree-<name>, then starts Claude inside it:
claude --worktree feature-auth # in terminal 1
claude --worktree fix-checkout # in terminal 2Add .claude/worktrees/ to your .gitignore so the copies don't show up as new files. A worktree is a fresh checkout, so files git ignores (like .env) are missing. List them in a .worktreeinclude file at your project root and Claude copies them into each new worktree. When you exit, Claude asks whether to keep or remove a worktree that has changes. Our worktrees guide covers merging and cleanup.
Subagents, each in its own worktree
Subagents are helpers that one Claude session sends off to do a focused job, such as running tests or reading docs. They report a summary back. You can make a custom subagent always work in its own worktree by adding one line to its file in .claude/agents/:
---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---More on writing these in Claude Code subagents.
Claude Code agent teams
Agent teams go one step further. One session becomes the team lead and starts teammates, each a full Claude Code session. They share a task list, claim tasks, and message each other directly. As of November 2026 the feature is experimental and switched off. Turn it on in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Then ask in plain words, for example: "Spawn three teammates: one builds the API in src/api, one builds the page in src/pages, one writes tests in tests/. Each one only edits its own folder." Anthropic suggests starting with 3 to 5 teammates and about 5 or 6 tasks each. In the terminal, press the up and down arrows in the agent panel to pick a teammate and Enter to read or message it.
What goes wrong: worktrees start empty of installed packages, so each one needs its own npm install (or equivalent) before it can run. Merging can still clash if two branches changed the same lines, so you have to settle those by hand. Agent teams add their own quirks, listed in Anthropic's docs: /resume does not bring back in-process teammates, task status sometimes lags, there is one team per session, teammates can't start their own teams, and teams use far more tokens. Anthropic's cost page puts it at roughly 7 times a normal session when teammates run in plan mode. All of this is Claude only.
Way 4: a session manager that watches every agent
The last step is a Claude Code session manager: one screen that shows every agent, tells you which one needs you, and lets you jump in. There is a free built-in option in the terminal and there are visual apps.
Built in: Claude Code background agents and agent view
Claude Code can start a session that runs in the background with no terminal attached. claude agents then opens agent view, a single list of all those sessions:
claude --bg --name "flaky-test-fix" "investigate the flaky settings test"
claude --bg --worktree "add dark mode to the settings page"
claude agents # one screen for every background session
claude attach flaky-test-fix # open the full conversation
claude logs flaky-test-fix # recent output only
claude stop <id> # stop it, using the ID it printedEach row shows a state: working, needs input (yellow), idle, completed (green), failed (red) or stopped. Press Space on a row to peek at the latest output or the question it is waiting on, and type a reply without leaving the list.
Visual: VibeCodingDeck
VibeCodingDeck is a desktop app for Windows 10/11 and Apple silicon Macs that turns this into a grid you can see without typing commands:
- Up to 12 agents on screen, each in its own pane on its own project, and up to 6 decks.
- A status light per pane (working, idle, waiting, done), three alert sounds, and a jump to whichever agent is waiting.
- One alert when the whole fleet has finished.
- Safe copies: each agent can work on its own copy of the project (git worktrees under the hood), and you merge the good work back.
- Save points to roll back if an agent makes a mess.
- Search across every terminal at once, and hand a stuck job to a different AI.
- Claude Code beside Codex, Gemini CLI, Grok, GitHub Copilot, Qwen, Kimi and Antigravity.
What goes wrong: agent view is a research preview, so Anthropic says its screens and shortcuts may change. It lists Claude sessions only and lives in the terminal. VibeCodingDeck costs $29/month, doesn't run on Linux, and needs an Apple silicon Mac rather than an Intel one. Neither removes the cost of running many agents, which the next section covers. For alternatives built on tmux, see Claude Squad alternatives.
How many parallel agents your plan can feed
Anthropic's agent teams page says there is no hard limit on the number of teammates. The real ceiling is your plan. Every agent draws from the same 5-hour and weekly usage windows, and cloud sessions share those limits with everything else on your account. Anthropic's agent view page puts it plainly: running ten agents in parallel uses your quota roughly ten times as fast as running one.
Anthropic's own sizing advice for teams is a good rule for any parallel setup: start small, and add agents only when the work can really run side by side. They note that three focused teammates often do better than five scattered ones. If one agent's job depends on another's result, run them one after the other instead. For a way to watch usage while agents run, see the Claude Code usage tracker. For planning how work splits between agents, read AI agent orchestration.
Checklist for running Claude Code agents side by side
- Each agent has its own project, or its own worktree or safe copy of the project.
- Each agent owns a different set of files, written into its first prompt.
.claude/worktrees/is in your.gitignore.- Secrets like
.envare listed in.worktreeincludeso new worktrees can run. - Every session has a name you will recognise (
/renameor--name). - You have a way to hear or see when an agent waits for you.
- You committed or took a save point before starting anything risky.
- You checked your usage before launching a big batch of agents.
- Agents that depend on each other's work run one after another, not together.
- You review each branch's diff before merging it back.
- Finished worktrees and leftover tmux sessions get cleaned up.
Sources
Run up to 12 AI coding agents in one window.
Claude Code, Codex, Gemini, Grok and more, side by side. Windows and Mac. From $29 a month.
Get startedKeep reading
Terminal multiplexers
Claude Code and tmux for beginners: panes, keys and Windows options
Git first, agents second
Claude Code worktrees, starting with plain git worktree
Hands-on Claude Code guide
Claude Code subagents: build a custom agent step by step
Explainer
AI agent orchestration for coding: the words, the patterns and a worked example
Agent manager
Claude Code dashboard: the six things you need to see at a glance
Windows walk-through
Claude Squad on Windows: what works, what breaks, what else to try