How to run multiple Claude Code agents in parallel

Why run more than one Claude Code session?#

One Claude Code session works through a task step by step. When a change has independent parts (an API, its tests, a migration, the docs), running a session for each part finishes the whole thing sooner and keeps each session's context focused on one job. A second session is also a natural reviewer for the first.

The two problems you hit immediately are collisions (two sessions editing the same files) and coordination (you relaying work and results between them). Each approach below handles them differently.

Option 1: several terminals on one checkout#

The simplest setup is to open two or three terminal tabs (or tmux panes) in the same repository and start claude in each. It needs nothing new, and it is fine when the sessions only read code or touch clearly separate files.

It breaks down quickly. Every session edits the same working tree, so one session's half-finished change becomes another session's confusing state, and a git checkout in one pane changes the files under all of them. You are also the only way the sessions can share anything: you copy the plan from one tab and paste it into another.

Option 2: one git worktree per session#

Git worktrees solve collisions. A worktree is a second working directory for the same repository on its own branch, so each Claude Code session gets its own files:

git worktree add ../myapp-api -b agent/api
git worktree add ../myapp-tests -b agent/tests

cd ../myapp-api && claude      # session 1
cd ../myapp-tests && claude    # session 2

Each session now commits to its own branch, and you merge the branches when they are done. When a branch is merged, remove its worktree with git worktree remove ../myapp-api.

Worktrees fix the files but not the coordination: the sessions still cannot ask each other anything, and you still track which terminal is doing what and which one is waiting for you.

Option 3: subagents inside one session#

Claude Code can also start subagents from within a single session to work on parts of a task and report back. This keeps everything in one conversation and is a good fit for research or focused sub-tasks. It stays inside one provider and one session, though: you cannot bring a Codex or Gemini agent into it, and long-running parallel edits still need separate branches.

Option 4: a coordinated team on a canvas#

MAO combines the parts above into one place. Each Claude Code session (or Codex, Gemini CLI, Grok or OpenCode session) is a real terminal on a canvas, and three things make them a team:

• Layers are worktrees. Put an agent on a layer and it works on its own branch in its own working tree, created for you. You see the diff on the canvas and land it when it is ready.
• Wires let agents talk. Connect two sessions and they can send each other tasks and get results back with the mao command, so the reviewer reaches the author directly instead of through you.
• Attention comes to you. When a session finishes, fails or waits for an approval, its node says so and you get a notification, so you never hunt through tabs.

An agent asks its connected reviewer from its own terminal:

mao ask reviewer "Check the new /sessions endpoint for missing tests"

Because every node is the agent's own CLI, each session keeps its own login, subscription and model. You can run two Claude Code sessions on two different accounts side by side.

Which approach should you use?#

How to keep parallel agents from colliding#

• One branch per agent that edits code. This single rule prevents most problems.
• Split by boundary, not by line. Give agents whole files or modules, not parts of the same file.
• Write the plan down once. A shared specification note keeps every agent on the same interface instead of each one inventing its own.
• Make one agent the reviewer. It reads every branch before you merge, so contradictions surface early.
• Merge often. Short-lived branches drift less than long ones.

Frequently asked questions#