How to orchestrate multiple Claude Code agents

There are three distinct approaches, and they answer different questions. Subagents split a task inside one session. Agent Teams run several full sessions that talk to each other. An orchestrator such as Orgabot runs each piece of work as its own isolated job and decides, on evidence, whether that work is finished. You can also simply run several Claude Code sessions yourself in separate git worktrees; the guide to running coding agents in parallel covers that manual route step by step.

Everything below about subagents and Agent Teams comes from Claude Code’s own documentation as it read when this page was last updated. Agent Teams in particular is changing quickly, so treat the Agent Teams docs as the source of truth.

Agent Teams coordinate several independent Claude Code sessions. One session is the team lead: it spawns teammates, creates tasks, and synthesizes results. Teammates each have their own context window, claim tasks from a shared task list (with dependencies between tasks and file locking so two teammates cannot claim the same one), and message each other directly through per-agent mailboxes. You can talk to any teammate yourself, and teammates can run inside your terminal or, with tmux or iTerm2, in split panes.

Agent Teams is experimental and disabled by default. To try it, set the environment variable in your shell or in settings.json, then ask for a team in plain language in an interactive session:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Spawn three teammates to review PR #142: one on security,
one on performance, one on test coverage. Report findings.

The documentation is candid about where it fits. Teams use significantly more tokens than a single session, because every teammate is a separate Claude instance. They work best for research, review, debugging with competing hypotheses, and new features that split cleanly into separately owned files; for sequential tasks or same-file edits, a single session or subagents do better. The recommended starting size is three to five teammates.

The documented limitations are worth reading before you rely on a team:

• No session resumption for in-process teammates: /resume and /rewind do not bring them back.
• Task status can lag: a teammate may not mark a task complete, which blocks the tasks that depend on it.
• One team per session, and no nested teams: teammates cannot spawn teammates, and the lead is fixed for the session.
• Teammates start with the lead’s permission mode, and their permission prompts surface in the lead session.
• Teammates are not spawned in non-interactive (-p) sessions, including Agent SDK sessions.
• Two teammates editing the same file overwrite each other, so the docs advise giving each teammate its own set of files.

For quality control, Agent Teams exposes hooks: TeammateIdle, TaskCreated, and TaskCompleted, each of which can exit with code 2 to send feedback and block the transition. That is a real mechanism for enforcing rules. It is also one you design, write, and maintain yourself.

Orgabot coordinates the work. Each instruction becomes a mission. Orgabot creates an isolated git worktree for it, runs a coding worker there (the claude CLI is the default worker, so this is Claude Code doing the editing), commits the result, and then runs a sequence of gates that the worker cannot skip or satisfy by describing its own success:

• Verify: Orgabot runs the project’s own registered test command against the committed change and gates on the exit code. A worker saying it is done is not evidence.
• Review: an independent reviewer reads the diff. The reviewer is never the agent that produced the change, and findings go to a fix round that is re-verified and re-reviewed.
• Deliver: the change opens as a draft pull request. Editing a branch is automatic; opening a PR, merging and deploying require policy or your explicit approval.
• Hold: when a gate fails or authority is missing, the mission stops with a named reason and keeps its worktree, branch and session, rather than guessing.

From Orgabot’s framework/ directory:

npm run orgabot -- project add ~/code/myapp --verify "npm test"
npm run orgabot -- mission myapp "Add rate limiting to the public API" --background
npm run orgabot -- mission myapp "Migrate the settings page to the new form library" --background
npm run orgabot -- status
npm run orgabot -- ship myapp --all   # draft PRs, review loop, then the merge gates

Several missions can run at once. Each has its own worktree, and a host-wide admission budget queues work beyond what your machine can carry rather than starting it and pausing it later. Two missions on the same project that name overlapping files serialize, so the second waits for the first to merge instead of producing a conflicting pull request. The mission terminal in the dashboard streams each mission’s output and lets you steer or interrupt it, and shipping and review documents the review loop.

If you want roles, Orgabot can route missions to roles in an org chart you staff with agents or people, each with its own scoped GitHub access, so an agent never borrows your personal credentials. That is optional: --no-org runs a mission on your own credentials with every gate above still in place. The organizations and roles page covers the model.