A Claude Code orchestrator is a control loop, not a launcher. Split work into independent tasks with explicit acceptance tests, give every editing session its own git worktree and branch, track a small set of states, review each diff with a fresh reader, and merge in dependency order. Use subagents for bounded research or delegated work inside one conversation; use separate sessions when outputs deserve separate branches, independent retries, and independent review. Plain tmux and git are enough for two or three agents. Conductor adds a focused Mac worktree board. Continuum adds a cross-device fleet view across hosts and providers. Orchestration pays only while saved execution time exceeds setup, coordination, and review cost.
- The orchestrator owns task boundaries, state, review, and merge order. The agents own execution.
- Every editing agent gets one worktree, one branch, one task, and one acceptance contract.
- Use subagents for bounded delegation inside one session; use separate sessions for independently reviewable changes.
- Model the fleet as a queue of explicit states, not a row of terminal tabs.
- Review the diff and test evidence, never the confidence of the final message.
- Merge in dependency order and rebase the remaining branches after every shared change.
- Two to four agents is the useful range for most solo developers. Review capacity is the hard ceiling.
What orchestration actually means
Coding agent orchestration is the work around the model call. A launcher can open four Claude Code processes. An orchestrator decides what each process may touch, records what state it is in, notices when it is blocked, checks what it produced, and controls how the result reaches the main branch. Conflating those jobs is why many so-called fleets are only terminal windows with expensive processes inside them.
The five jobs in a Claude Code orchestration loop.
| Job | Question it answers | Failure when omitted |
|---|---|---|
| Decompose | Can this task finish without another agent changing its inputs? | Agents guess at interfaces that do not exist yet |
| Isolate | What files and branch may this agent change? | Concurrent edits overwrite or contaminate each other |
| Observe | Is it running, waiting, failed, or ready for review? | You poll terminal tabs and miss blocked work |
| Verify | Did the branch satisfy its acceptance contract? | A persuasive summary substitutes for evidence |
| Integrate | In what order do approved branches rejoin main? | Green branches conflict or invalidate one another |
The useful mental model is a small build system with humans in the review nodes. Tasks form a dependency graph. Independent nodes may run concurrently; dependent nodes wait. Each successful node emits a branch, a diff, and verification evidence. The human or CI gate decides whether that artifact advances. If that sounds less glamorous than an autonomous swarm, good. Reliable orchestration is deliberately boring.
Start with the mechanics in running parallel Claude Code sessions and the repository model in the complete git worktree guide. Orchestration is the layer that decides when to use those mechanics and when not to.
Choose the right unit of parallelism
Claude Code has several ways to fan work out. They are not interchangeable. The key distinction is who owns the resulting context and branch.
Four ways to run more than one agent.
| Approach | Isolation | Result returns as | Use it for |
|---|---|---|---|
| Separate Claude Code sessions | Separate conversation; separate files with worktrees | One branch and transcript per task | Independent features, fixes, audits, or A/B attempts |
| Claude Code subagents | Fresh context; shared files by default | A summary inside the parent session | Research, test writing, focused review, codebase search |
Subagents with isolation: worktree | Fresh context and temporary worktree | A delegated result folded into the parent | Bounded edits whose parent still owns the outcome |
| Agent teams | Separate Claude instances coordinated by a lead | A coordinated task graph | Large, communication-heavy work worth the extra token load |
Use a separate session when the output deserves its own lifecycle. You want to restart it without disturbing other work, inspect its branch alone, send it to a fresh reviewer, open a pull request, or discard the whole attempt. A feature, migration, or bug fix usually belongs here. The session is an independently accountable worker.
Use a subagent when the parent conversation should remain the owner. Searching a large repository, checking a narrow security question, or writing tests for a finished API can be delegated and summarized back. The tradeoff is context loss: the subagent starts fresh and returns a summary, so it is a poor choice for work whose value lives in twenty minutes of discussion. The full configuration model is covered in Claude Code subagents.
Agent teams add communication among Claude instances, which is valuable only when the work truly needs coordination during execution. They also multiply context and token consumption. If three tasks can be written down independently, three worktree sessions are simpler, cheaper, easier to restart, and easier to review.
Decompose work before launching anything
Parallelism begins on paper. Before launching, write the dependency graph and force every proposed lane through one question: could this agent complete against the current base without receiving code from another active lane? If the answer is no, those tasks are sequential no matter how many models are available.
Good and bad fleet boundaries.
| Parallelises cleanly | Looks parallel, is not |
|---|---|
| Fix an auth timeout; update unrelated docs; bump a dependency | Define a schema; implement the server against it; implement the client against it |
| Build feature A in one module; add tests to stable module B | Refactor a shared type while another agent adds consumers |
| Run two models on the same hard task and keep one branch | Ask two agents to co-author one implementation |
| Audit three independent trust boundaries read-only | Split one debugging chain into symptoms, cause, and fix |
A good task packet is small enough to review and complete enough to test. Give it a goal, a literal file or subsystem boundary, an explicit non-goal, acceptance commands, and an output contract. Include known constraints such as no commit, no network, or no schema changes. Name the branch after the outcome, not the agent or model, because six hours later the reviewer needs to understand fix/refresh-race, not claude-3.
TASK: Fix duplicate refresh requests in the token loader.
SCOPE: src/token-loader.ts and its tests only.
NON-GOALS: no cache format changes; no UI changes.
BASE: origin/main at 4a3f2c1.
ACCEPTANCE:
npm test -- token-loader
npm run typecheck
OUTPUT:
one branch; concise root cause; commands and exit results; caveats.Keep a shared contract lane when several tasks depend on a new interface. Have one agent propose the schema or API, review and merge that small change, then fan implementation out from the new base. This one deliberate pause removes a large class of speculative integration work.
Make worktrees the write boundary
Every editing session needs its own checkout. Git worktrees are the right primitive because each directory has independent files, index state, and checked-out branch while sharing object storage and history. The result is cheap isolation with a normal branch at the end. Claude Code worktree support now handles the common path directly.
# let Claude Code create and enter each worktree
claude --worktree auth-timeout
claude --worktree docs-refresh
claude --worktree dependency-bump
# or create an existing/specific branch yourself
git worktree add -b fix/auth-timeout ../app-auth origin/main
cd ../app-auth && claudeClaude-created worktrees live under .claude/worktrees/<name>/ by default and should be ignored. A committed .worktreeinclude can copy selected gitignored environment files into each one. Dependencies still need installation, preferably through a package manager with a shared content-addressed store. Dependencies across worktrees covers the disk and cache tradeoffs.
# .gitignore
.claude/worktrees/
# .worktreeinclude
.env
.env.local
config/local.jsonStart every lane from a recorded base commit. If main moves while the fleet is running, do not silently update half the worktrees. Merge the dependency that matters, rebase affected branches deliberately, rerun their gates, and leave independent branches alone. Reproducibility is worth more than theoretical freshness.
Launch with a contract, not a paragraph of hope
The launch prompt should be boring enough that another engineer can audit it. Put the task packet in the repository issue, a scratch file, or the command itself, and give the session a stable name matching its branch. The model needs the objective and constraints; the operator needs a handle that survives terminal reordering.
Record the base and reserve the lane
Capture the base commit, task owner, branch, worktree path, acceptance commands, and dependencies before a process starts. This is the fleet ledger.
Provision the worktree and environment
Create the branch, copy only required local configuration, install dependencies, and prove the baseline gate is not already failing.
Start Claude Code with one bounded task
Give the session its own task packet. Ask it to stop and report when a non-goal becomes necessary rather than expanding scope silently.
Publish state, not narration
The session should end with changed files, acceptance command results, remaining risks, and a branch state. A long story about the implementation is optional.
For a small local fleet, tmux is enough. Use one session per repository and one named window per lane. The terminal multiplexer gives processes durability and a stable index; git gives each window its write boundary.
tmux new-session -d -s app -n auth "cd ../app-auth && claude"
tmux new-window -t app -n docs "cd ../app-docs && claude"
tmux new-window -t app -n deps "cd ../app-deps && claude"
tmux list-windows -t app
tmux attach -t appMonitor a fleet as a state machine
A useful monitor answers what needs attention without opening a transcript. Keep the state vocabulary small and operational. More detail belongs inside the session, not in the fleet index.
A state model that works from tmux to a dedicated orchestrator.
| State | Meaning | Operator action |
|---|---|---|
| Queued | Task is defined but a dependency or slot blocks launch | Wait or change priority |
| Running | Agent is producing work | Leave it alone |
| Needs input | Permission, decision, secret, or ambiguity blocks progress | Answer narrowly |
| Verifying | Implementation stopped; gates are running | Watch for deterministic evidence |
| Review ready | Diff and gate results are available | Assign a reviewer |
| Failed | Process, environment, or acceptance gate failed | Classify before retrying |
| Approved | Review accepted the branch | Place it in the merge queue |
| Integrated | Merged and downstream branches updated | Clean up the lane |
Do not collapse every non-running session into failed. A permission prompt, a test regression, a dead process, a rate limit, and an unreachable host need different responses. Retrying all of them burns quota and often repeats the same failure. Classify the blocker, preserve the exact error, and decide whether the fix belongs to the task, the environment, or the orchestration layer.
With plain CLI tools, the ledger can be a Markdown table plus tmux list-windows, git worktree list, and git -C <path> status --short. Refresh it on meaningful transitions rather than every token. A dedicated Claude Code orchestrator should derive the same states from process activity, permission gates, plan readiness, test output, diff presence, and pull-request status.
Quota belongs in the fleet view because parallel sessions share the account window. Four agents may consume roughly four times the allowance. Check Claude Code rate limits before launching the fourth lane, and use a usage dashboard when the fleet spans accounts or providers.
Review and merge are part of orchestration
The orchestration loop is incomplete when an agent says done. Completion produces a candidate branch. Acceptance requires reproducible gates and a diff review by someone or something that did not write the change.
- Freeze the task boundary. Record the final base and head commits. Any later edit starts a new review cycle.
- Run the named gates. Capture command, exit code, and relevant output. Separate a source failure from an environment blocker.
- Review the branch diff. Check scope first, correctness second, security boundaries third. Ignore the author summary until after the diff.
- Use a fresh reviewer. A read-only Claude Code subagent or separate session can look for concrete defects without inheriting the author context.
- Merge one branch. Choose dependency order, update main, then rebase and reverify every affected remaining branch.
- Remove the worktree. Keep the branch or pull request as the durable artifact; the checkout is disposable.
git -C ../app-auth diff --stat origin/main...HEAD
git -C ../app-auth diff origin/main...HEAD
# run the contract inside the isolated checkout
npm --prefix ../app-auth test -- token-loader
npm --prefix ../app-auth run typecheck
# publish for CI and review
git -C ../app-auth push -u origin fix/auth-timeout
gh pr create --fill --head fix/auth-timeoutOne pull request per worktree preserves attribution, CI, and rollback. Squashing every lane into one integration branch before review erases those benefits. If a fleet produces more branches than you can review carefully, reduce concurrency rather than weakening the gate.
The orchestration landscape, honestly
There is no single best Claude Code orchestrator. The right surface depends on whether the hard problem is process durability, a dense desktop board, or a fleet spread across devices and hosts.
Three practical operating surfaces.
| Surface | What it does well | What you still own |
|---|---|---|
| Plain tmux, git, and CLI | Transparent, scriptable, works on any shell host, no product dependency | Worktree provisioning, status extraction, review queue, mobile ergonomics |
| Conductor for Mac | Focused GUI for parallel coding agents in isolated workspaces, with review and merge flow | A Mac-centered operating model; decide separately how remote or phone access fits |
| Continuum | One session fleet across Mac, web, iPhone, Watch, and enrolled hosts, with plan, diff, PR, terminal, files, and usage state | Task decomposition, acceptance criteria, and the final review decision |
Conductor came from the former Melty team in Y Combinator and made the worktree board legible: start agents in isolated copies, see what each is doing, then review and merge. It announced a $22 million Series A on March 30, 2026. Its cloud workspaces extend the local Mac model with Vercel Sandbox infrastructure. That is a serious product for people whose day is a dense board of local or cloud workspaces, not a toy to dismiss because tmux exists.
Continuum starts from the same need for isolated, reviewable sessions but treats the fleet as cross-device. The Mac, web, and native iPhone surfaces open the same managed sessions; enrolled Mac, Linux, and Windows hosts can do the execution; the iPhone can create and steer sessions, approve plans, interrupt work, read diffs, follow pull requests, use a terminal, and inspect files. Those are product claims already documented in Continuum mobile, the device fleet, and Sessions.
Plain tmux remains the correct choice when there are two agents, one host, and an operator who wants no additional layer. A GUI earns its place only when it removes more polling and coordination than it introduces. Keep the underlying branches and commands understandable so leaving a tool never means losing the work.
When orchestration pays, and when it is overhead
Parallel agents save wall-clock time only on the portion of work that is independent. They add setup, context packaging, quota consumption, review, merge, and failure-classification cost. The economic test is simple even when the inputs are estimates.
benefit = sequential execution time - parallel critical path
overhead = decomposition + setup + monitoring + review + integration
run the fleet only when benefit > overhead
and review capacity >= expected completed branches| Orchestration usually pays | Orchestration usually loses |
|---|---|
| Three independent changes with stable tests | One small fix in one file |
| A repository-wide mechanical migration split by module | An ambiguous bug whose cause is still unknown |
| Parallel read-only audits of separate boundaries | Several edits to the same shared types |
| A/B implementations where one branch will be discarded | A chain where every task consumes the previous output |
| Long tests or builds that can run independently | Work that takes less time than provisioning a clean worktree |
The hidden limit is arrival shape. Three agents often finish together because they started together. That creates a review burst, and branches wait while main changes underneath them. Stagger launches so the first review arrives before the last agent starts, or keep one slot empty for urgent fixes and verification. Maximum concurrency is rarely maximum throughput.
Measure the result over a week. Track elapsed task time, first-pass gate rate, review minutes, rework, and discarded branches. Add quota or estimated cost from Claude Code cost tracking. If more lanes increase output but lower accepted changes per review hour, the fleet is growing in the wrong direction.
Questions people ask
It is the control loop around several Claude Code workers: decomposing tasks, isolating each editing session, tracking state and blockers, verifying results, reviewing diffs, and integrating approved branches in the right order. Merely opening several terminals is parallel execution, not orchestration.
Give every editing agent its own git worktree and branch, one bounded task, and explicit acceptance commands. Track each lane from queued through review ready, then review and merge branches one at a time in dependency order.
Use subagents for bounded work that should return to one parent conversation, such as research, focused review, or tests. Use separate sessions for changes that need independent branches, retries, pull requests, and review. Add isolation: worktree to a subagent when it must edit without sharing the parent checkout.
They can start there, but it is not safe. They can overwrite files, stage each other's changes, and run commands against moving inputs. A worktree per agent gives each one independent files and branch state.
Usually two to four editing sessions, and often only two plus a reviewer. Machine capacity is rarely the limiting factor. Shared account quota, simultaneous blockers, and the number of diffs you can review carefully set the useful ceiling.
Track a small set of actionable states: queued, running, needs input, verifying, review ready, failed, approved, and integrated. A tmux session plus a Markdown ledger works for a small fleet; a dedicated orchestrator can derive those states across hosts and devices.
Yes. Conductor is a focused Mac application for running coding agents in parallel isolated workspaces and reviewing and merging their output. Its cloud workspaces extend that model with remote Vercel Sandbox execution.
Continuum projects managed worktree sessions into Mac, web, iPhone, and Watch clients and can run them on enrolled hosts. It attaches chat, plan, diff, PR, terminal, and files to the same session and shows providers and usage in the fleet. The human still owns decomposition and final review.
When the task is small, ambiguous, tightly sequential, or concentrated in shared files. If setup, context packaging, review, and integration take longer than the parallel time saved, one well-directed session is the faster system.
Sources
Every figure above was read from these pages on 3 August 2026. Vendors reprice without notice; if you find a stale number, tell us.