Claude Code orchestration: how to run multiple Claude Code agents without losing track

Claude Code orchestration means one agent, or you, splitting a job into pieces, handing each piece to a separate Claude Code session with its own context, and merging the results. You can do it with subagents, parallel sessions in git worktrees, or a lead agent with teammates. The hard part is ownership, handoffs, approvals and keeping sessions alive.

What does orchestration mean in Claude Code?

Orchestration is everything around the work itself: deciding how to split a job, which agent takes which piece, what context each one gets, and how the pieces come back together. In Claude Code you have three building blocks.

• Subagents. Workers that one session spawns. Each gets its own context window, does a side task, and returns a summary to the session that started it.
• Parallel sessions. Several Claude Code sessions you start yourself, usually one per git worktree so their edits never collide. Here you are the orchestrator.
• A lead agent with teammates. One session plans and assigns, the others execute and report back. Claude Code ships this as agent teams, an experimental feature that is off by default.

The three differ on two questions: who splits the work (you or an agent), and where it runs (your laptop, or a machine that stays on). A common path: start with parallel sessions, add subagents for research and review, then hit the limits of both once more than three or four things are in flight at the same time.

How do I set up subagents in Claude Code?

A subagent is a markdown file in .claude/agents/ (one project) or ~/.claude/agents/ (all your projects). The frontmatter names it, says when to use it, and limits its tools:

---
name: test-writer
description: Writes and runs unit tests for one module. Use after a feature is implemented.
tools: Read, Grep, Glob, Edit, Bash
---
You write focused unit tests and run them.
Report: files changed, tests added, what still fails.

Three habits make subagents worth having:

1. Narrow descriptions. Claude delegates by matching the task against the description, so a vague one gets ignored or misused.
2. Restricted tools. A reviewer that cannot edit files cannot quietly "fix" the code it was asked to judge.
3. A fixed report format. The subagent starts with a fresh context, and its final summary is all the parent sees. Ask for changed files, open questions and anything it could not verify.

Subagents are the cheapest form of orchestration because everything stays inside one session. That is also their limit: they live and die with that session.

How do I run Claude Code sessions in parallel with git worktrees?

When two tasks touch the same repo, give each one its own checkout. Claude Code can create it for you:

claude --worktree feature-auth
claude --worktree fix-billing-webhook

Each command starts a session in .claude/worktrees/<name>/ on a new branch. Plain git worktree add ../app-auth -b feature-auth works too if you prefer to manage paths yourself.

Habits that keep this sane:

1. One task per worktree, one branch per task, one pull request per branch.
2. Copy what a fresh checkout lacks (.env, local config) before starting. A .worktreeinclude file does this automatically.
3. Put the task brief in the first prompt: goal, files in scope, how to verify, where to write the result.
4. Merge through pull requests, so you read every branch before it lands.

The trade-off is that you are now the orchestrator. You write every prompt, remember which tab owns which branch, and answer every permission prompt across all of them. Claude Code's agent view (claude agents, a research preview) puts background sessions on one screen, which helps with tracking. You still write each prompt and answer each question. That is fine for three sessions. At eight, the coordination becomes the job.

How do I get a lead agent to split the work?

If you would rather have Claude do the splitting, give one session the manager role and keep it out of the code. A prompt that works:

You are the lead. Do not edit code yourself.
1. Read docs/spec.md and break it into tasks small enough to finish in one session.
2. For each task write: goal, files it owns, inputs, definition of done.
3. No two tasks may own the same file.
4. Hand each task to a worker, then wait until every worker has reported.
5. Check each result against its definition of done. Report what is done, what failed, and what needs me.

Claude Code's agent teams (enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) give this pattern a shared task list with pending, in progress and completed states, plus direct messages between teammates. Anthropic's docs suggest starting with 3 to 5 teammates and splitting the work so each one owns different files, because teammates run in the same checkout. The lead has failure modes of its own; how Claude manages other agents covers prompting and reviewing a lead in detail.

Where does Claude Code orchestration break?

The work itself is rarely the problem. The seams between agents are.

• Context handoff. A worker starts with what you put in its brief and nothing else. Every decision the lead made in conversation and never wrote down is gone. Handoffs lose information by default.
• Ownership. Two agents edit the same file, or a task still says "in progress" long after its worker stopped. Nobody, including you, can say who owns what right now.
• Approvals. Permission prompts from every worker land in one terminal, and while you are away the work waits. In headless runs, anything that would prompt is denied, so the run ends with part of the job skipped.
• Keeping sessions alive. A session in a terminal ends with that terminal or that machine, and any session stops making progress once its login expires. Overnight work needs a computer that stays on.
• Usage limits. Parallel sessions multiply token use, so a plan's limit arrives sooner, and it tends to arrive mid-task.

Fix the seams and the same agents get far more done.

How do I fix handoffs, ownership and approvals by hand?

You can get most of the way with files and discipline:

1. Write every handoff to a file. One brief per task in a tasks/ folder, with goal, context, constraints, definition of done and where the output goes. Workers read the brief, and the lead never relies on memory.
2. Make ownership explicit. Each brief names its owner and the files it may touch. Workers update their own brief's status and nothing else.
3. Pre-approve the safe actions. Allow reads, tests and edits inside the repo in your settings, so the prompts that remain are the ones that matter: deploys, deletes, anything public.
4. Batch decisions. Tell workers to collect questions in a "needs you" section of their brief and keep going on everything else.
5. Run long work on a machine that stays on. A small cloud server works, with claude setup-token for a long-lived login.
6. Check results against the definition of done. A summary that says "done" is a claim. A passing test run is evidence.

You can build all of this yourself, one script at a time. Its weak spot is that you still have to run it.

How does Kavela orchestrate Claude Code agents?

Kavela runs this pattern as a product. You talk to one agent, Kav, who plans the work, files each piece as a task, and hands it to the right worker. Every task, routine and event lands on a calendar (month, week and day views), so you see the week's agent work at a glance.

Each worker runs in its own cloud computer (a container with a real shell, files, git and a browser) and keeps working after you close the tab or your laptop. Per agent, you pick a Kav AI tier or "My Claude plan". With your plan, Claude Code runs inside that agent's cloud computer on your own subscription. You sign in once from a card, and the worker still gets the workspace's files, skills and connected apps. With several accounts connected, Kavela rotates when one hits its usage limit. If all are at their limit, the run pauses and asks you once: wait, finish on Kavela credits, or cancel.

Anything that needs you (a sign-in, a choice, a deploy) waits in one Approvals inbox, which you can also answer from Telegram. Everything else runs, and each task ends with its deliverables attached.

Kavela is in early access and runs on your own Claude subscription, with a 14-day free trial. Start your free trial