Multi-Agent Claude Code: Subagents, Teams, Workflows

Start with subagents. Move to agent teams (experimental, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) only when workers must talk to each other, and use dynamic workflows for big fan-out jobs that need dozens of agents. That order matches cost: subagents are the cheapest way to parallelise, teams cost the most per worker, and workflows trade tokens for scale and repeatability.

Everything here was checked on 25 Oct 2026 against Anthropic’s run agents in parallel, agent teams, dynamic workflows and subagents docs.

The multi-agent options in Claude Code

Anthropic’s docs list five ways to work on several tasks at once. They differ in who coordinates the work and whether the workers can talk to each other:

Approach	Who coordinates	Workers talk to each other?	Status	Use it when
Subagents	Claude, inside one session	Report back to the caller	Stable	A side task would flood your context with logs or search results
Agent view (claude agents)	You	Report only to you	Research preview	You hand off independent tasks and check back later
Agent teams	A lead session	Yes, directly, plus a shared task list	Experimental, off by default	Workers need to share findings and challenge each other
Dynamic workflows	A script Claude writes	Through the script	Paid plans and the API	A job needs dozens to hundreds of agents, or cross-checked results
Projects	Claude, across cloud threads	Through the project	Public beta on Pro and Max	Work spans days and should run while your machine is off

Three helpers support all of these: worktrees give each session its own checkout, cross-session messaging lets your own sessions pass notes, and /batch splits one large change into 5 to 30 worktree-isolated subagents.

Step 1: subagents

A subagent is a worker with its own context window, prompt and tool list. Claude spawns it, it does one job, and it returns a summary, so the main conversation stays small. You can ask for parallel work in plain English:

Research the authentication, database, and API modules in parallel using separate subagents

To make a reusable specialist, add a Markdown file to .claude/agents/ with name, description, and optionally tools and model. Our Claude Code subagents guide covers the file format, built-in agents, nesting and concurrency limits.

Subagents are the right default because results come back summarised. Their limit: they don’t coordinate with each other the way teammates do. The main agent manages all the work.

Step 2: agent teams

An agent team is several full Claude Code sessions. One is the lead: it splits the work, assigns tasks and combines the results. The teammates each run in their own context window, claim tasks from a shared list and message each other directly. You can also talk to any teammate yourself.

Turn agent teams on

Agent teams are experimental and disabled by default. Set the variable in your shell or in settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Then describe the team in an interactive session:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Teammates appear in a panel under the prompt. Use the arrow keys to select one and Enter to read its transcript or message it. For a pane per teammate, set "teammateMode": "auto" in ~/.claude/settings.json or start with claude --teammate-mode auto; split panes need tmux or iTerm2.

Two behaviours to know before you enable it:

• Teams can form on their own. With the variable set, a subagent that Claude names launches as a teammate, even if you didn’t ask for a team.
• Teams need an interactive session. In claude -p and Agent SDK runs, Claude doesn’t spawn teammates.

Run a team well

The agent teams docs give concrete guidance:

• Start with 3 to 5 teammates, and about 5 to 6 tasks per teammate. Three focused teammates often outperform five scattered ones.
• Start with research and review, such as reviewing a PR or testing competing bug hypotheses, before you try parallel implementation.
• Give each teammate its own files. Teams don’t use worktrees, and two teammates editing one file overwrite each other.
• Use Sonnet for teammates and shut them down when they finish. Each active teammate keeps using tokens until it exits.
• Tell the lead to wait if it starts doing the tasks itself: “Wait for your teammates to complete their tasks before proceeding.”

Current limitations

Because the feature is experimental, expect rough edges. /resume and /rewind do not restore in-process teammates, task status can lag, a session can have only one team, teammates cannot spawn their own teammates, and the lead cannot be changed. Shutdown can be slow, because teammates finish their current request first.

Step 3: dynamic workflows

A dynamic workflow is a JavaScript script that orchestrates many subagents. Claude writes the script for your task, and a runtime runs it in the background while your session stays free. The plan lives in code instead of in Claude’s turn-by-turn judgement, so a workflow can run dozens to hundreds of agents, have them check each other’s findings, and be saved and rerun.

Ways to start one:

• Run the bundled one: /deep-research followed by a question fans out web searches and returns a cited report.
• Ask for one: put the keyword ultracode in your prompt, as in ultracode: audit every API endpoint under src/routes/ for missing auth checks, or simply ask Claude to “use a workflow”.
• Watch and stop it with /workflows, which shows each phase, agent and token count.

Dynamic workflows are available on all paid plans, with Anthropic API access, and on Bedrock, Google Cloud and Microsoft Foundry. On Pro, turn them on from the Dynamic workflows row in /config. Claude Code shows a Large workflow warning when a run schedules more than 25 agents or its projected tokens pass 1.5 million. The warning is advisory and does not stop the run.

Subagents vs agent teams vs workflows

	Subagents	Agent teams	Dynamic workflows
Who decides what runs next	Claude, turn by turn	The lead, turn by turn	The script
Where results live	The caller’s context	A shared task list	Script variables
Typical scale	A few tasks per turn	A handful of long-running peers	Dozens to hundreds of agents
Token cost	Lowest	High, roughly proportional to team size	High per run
Works in claude -p	Yes	No	The keyword does not trigger a workflow there
Good first use	Codebase search, test runs	Parallel review, competing hypotheses	Codebase-wide audit, large migration

When multi-agent is a waste of tokens

More agents means more tokens, and not always better results. Anthropic’s engineering post on its multi-agent research system (June 2025) reported that agents typically use about 4 times more tokens than chat, and multi-agent systems about 15 times more. The same post says tasks where all agents need the same context, or with many dependencies between agents, are a poor fit, and that “most coding tasks involve fewer truly parallelizable tasks than research”.

Skip multi-agent when:

• The steps are sequential. Each one needs the previous result, so parallel workers just wait.
• Everyone edits the same files. You get conflicts, not speed.
• The task is small. Coordination overhead outweighs the gain; a single session is cheaper.
• You can’t check the result. Without tests or a clear deliverable, more agents produce more unverified output.

Before a big run, try it on a slice: one directory instead of the whole repo. Watch the per-agent tokens in /workflows or the subagent share in /usage, then scale up.

See it in practice

Claudekit itself is run by a team of scheduled AI agents with a human editor. The live activity board shows each agent’s schedule and what the team did in the last 7 days, which is a useful reality check on how much one well-scoped agent can do before you reach for a team.