11. Parallel agents
"Claude Code can split work across several Claude sessions at once, and there are five ways to do it. Subagents are workers Claude spawns inside one session; each gets its own context window and sends back only a summary. Agent view is where you dispatch background sessions and check on them. Agent teams put a lead session in charge of teammates that message each other. Dynamic workflows move the plan into a script that can run hundreds of agents and cross-check their results. Projects run long-lived threads in the cloud. Worktrees keep their file edits apart. The trade is always the same: you get speed and a clean main context, and you pay in tokens, because every worker spends its own."
The architect's line is the last one. Parallel is a cost decision, not a free speedup.
8 pictures, in order.
Use the arrow keys or the dots. Tap a picture to see it full size.
The facts someone can check.
The five approaches, in one table
| Approach | Who coordinates | Results go to | Status |
|---|---|---|---|
| Subagents | Claude, inside one conversation | The conversation that spawned them | Built in; Explore, Plan, and general-purpose ship by default |
Agent view (claude agents) |
You dispatch, then check back | Only you | Research preview |
| Agent teams | A lead session | Teammates message each other, shared task list | Experimental, off by default (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) |
| Dynamic workflows | A script Claude writes | Script variables; only the final answer reaches Claude | All paid plans; on Pro, turn on in /config |
| Projects | Claude, across cloud threads | One conversation shows which threads need you | Public beta, Pro and Max |
Three helpers sit alongside them: worktrees (a separate checkout per worker), cross-session messaging (Claude can message your other sessions; /list-agents shows who it can reach), and /batch (a skill that splits one large change into 5 to 30 worktree-isolated subagents).
What a subagent starts with
This is the question an interviewer uses to check you understand the mechanism.
- A fresh subagent starts with its own system prompt, a task message Claude writes for it, your CLAUDE.md files, a git status snapshot, and any skills its definition preloads. It does not see your conversation, your auto memory, or your output style.
- The built-in Explore and Plan subagents skip CLAUDE.md and git status to stay fast and cheap. They are read-only.
- A fork inherits everything: the whole conversation, the same system prompt, tools, and model. Because its prompt matches yours, it reuses your prompt cache, so a fork is cheaper than a fresh subagent for work that needs the same background.
- Either way, the worker's own tool calls stay out of your context. Only its final report comes back.
Four commands that sound alike
| Command | What happens | Does the result come back here? |
|---|---|---|
/subtask <task> |
Starts a forked subagent that runs in the background inside this session | Yes, as a message when it finishes |
/fork [prompt] |
Copies the conversation into a new background session (a new row in agent view) | No. The two are independent after the fork |
/background [prompt] (alias /bg) |
Moves this same session to the background and frees your terminal | It is the same session, just detached |
/branch [name] |
You switch into a copy; the original waits for /resume |
You are now in the copy (Module 10) |
With agent view turned off, /subtask isn't available and /fork starts a forked subagent instead.
Watching running work
/tasks(alias/bashes): background work in this session, including subagents that just finished.claude agents, from your shell: every background session, its state, and which ones need you. Not the same thing as/agents, which only points you at subagent files./workflows: running and finished workflows, the phase each is in, and how many agents have finished. You can pause, stop, or save a run from here./list-agents(alias/peers): the subagents, teammates, and other sessions Claude can message. Needs v2.1.224 or later and cross-session messaging turned on.
The numbers that bound it
/batch: 5 to 30 units, one background subagent per unit, each in its own worktree. Needs a git repository (or aWorktreeCreatehook).- Subagents: 20 running at once by default, nesting up to 3 layers below your main conversation. No cap on the total over a session.
- Workflows: 16 agents at once by default, 1,000 agents total per run, 4,096 items in one
parallel()call. ALarge workflowwarning appears past 25 agents or 1.5 million projected tokens, and it is advisory only. - Agent teams: start with 3 to 5 teammates and 5 to 6 tasks each. One team per session, and teammates can't start teams of their own.
- Subagent descriptions load every session. Past 15,000 tokens combined, Claude Code warns at startup.
Worktree isolation
claude --worktree <name>(or-w) starts Claude in.claude/worktrees/<name>/on a new branch,worktree-<name>.- While isolated, Claude Code blocks edits to the main checkout, commands that run in it, and git pointed back at it. It does not track what a shell command writes, so a plain
cpinto the main checkout isn't refused; permissions and the sandbox still apply. - Background sessions from agent view move into their own worktree before they edit.
/batchunits get one each. A subagent gets one if its definition saysisolation: worktree. - Agent team teammates do not get worktrees. Split the work so each teammate owns different files.
- New worktrees branch from the remote default branch. Set
worktree.baseRefto"head"to carry your unpushed work in. A.worktreeincludefile copies gitignored files such as.env.
Dynamic workflows: when the plan moves into a script
With subagents, skills, and agent teams, Claude decides what happens next, one turn at a time, and every result lands in a context window. A workflow is a JavaScript script that holds the loop, the branching, and the intermediate results itself, so Claude only sees the final answer. That is what lets it run dozens to hundreds of agents and have them check each other's findings.
- Try the bundled one:
/deep-research <question>. - Ask for one by including the word
ultracodein a prompt, or turn on/effort ultracodeto have Claude plan a workflow for every substantive task (which costs more on every request). - In
/workflows, presssto save a run's script. Saved to.claude/workflows/, it becomes a/commandfor everyone who clones the repo. - The size guideline tells Claude how many agents to aim for: small (fewer than 5), medium (fewer than 10, the default except on Pro), large (fewer than 50), or unrestricted.
- Admins can turn workflows off for the whole organization with
disableWorkflowsin managed settings.
When it helps, and what it costs
The docs give three questions: who coordinates, do the workers need to talk, and do they touch the same files. Underneath all three is cost. Agent view's own limitation note says ten background agents use quota roughly ten times as fast as one. Agent team token use grows with each teammate. Stay in one session for back-and-forth work, for phases that share heavy context, and for quick edits where spinning up a worker costs more than the work.
Answer out loud, then flip the card.
Mark each one honestly. Cards you miss stay flagged for review, in this browser.
A customer asks: "If Claude spawns a subagent, does it know everything we've discussed in this session?"
Not unless it's a fork. A fresh subagent starts with its own system prompt, the task message Claude writes, your CLAUDE.md files, and a git status snapshot. It doesn't see the conversation history, your auto memory, or your output style. A fork (started with /subtask, or by Claude while fork mode is on) inherits the whole conversation. If a rule must reach a fresh subagent, put it in CLAUDE.md or restate it in the delegation prompt.
What's the difference between /subtask and /fork?
/subtask starts a forked subagent inside your session. It runs in the background and its result comes back into your conversation. /fork copies the conversation into a separate background session that shows up as its own row in agent view. After the fork the two are independent; nothing the copy does enters your conversation unless one session messages the other.
A team wants to migrate 400 files from JavaScript to TypeScript. What do you recommend?
/batch migrate src/ from JavaScript to TypeScript is the packaged answer: Claude researches the codebase, splits the work into 5 to 30 independent units, shows the plan, and once approved runs one background subagent per unit, each in its own worktree, each running tests and publishing its change. For more control, ask for a dynamic workflow, which can run far more agents and verify results against each other. Either way, test on a small slice first, because every agent spends its own tokens.
When would you choose agent teams over subagents?
When the workers need to talk to each other. Subagents only report back to the conversation that spawned them. Teammates message each other directly and share a task list, which suits review, debugging with competing theories, or a feature split across frontend, backend, and tests. Caveats: agent teams are experimental and off by default, they cost noticeably more tokens, and teammates share one checkout, so you must split the work by file.
Two parallel sessions keep overwriting each other's changes. What's wrong and how do you fix it?
They're editing the same checkout. Give each its own git worktree: claude --worktree feature-a in one terminal and claude --worktree feature-b in another. Sessions dispatched from agent view do this automatically before their first edit, and a custom subagent can be pinned to its own worktree with isolation: worktree. If they're agent team teammates, worktrees aren't used, so assign each teammate different files.
A CFO asks why the Claude bill tripled after the team "started using agents." What do you tell them?
Parallel work multiplies token use, because every subagent, teammate, or background session spends its own tokens. Agent view's documentation says ten agents in parallel use quota roughly ten times as fast as one. The levers: use subagents only for genuinely independent or output-heavy work, prefer a fork when the worker needs the same context (it reuses the prompt cache), keep agent teams small (3 to 5), set the workflow size guideline to small or medium, and run any large workflow on a small slice first to measure.
What stops a runaway workflow from spawning agents forever?
Hard caps in the runtime: 1,000 agents total per run and 16 running at once by default. A Large workflow warning appears past 25 agents or 1.5 million projected tokens, but that warning is advisory and doesn't stop anything. You can watch each agent's token use in /workflows and stop the run there, usually keeping completed work. An admin can also turn workflows off for the whole organization.
How do you check on work running in parallel?
Depends where it runs. /tasks shows background work in the current session, including subagents that just finished. claude agents from your shell opens agent view, with every background session and which ones need you. /workflows shows workflow runs by phase. /list-agents shows which sessions and agents Claude can message.
Wrong answers that sound right.
Before you tap, say why each one is wrong.
Three moves in a fresh project.
Facts checked against code.claude.com/docs/en/agents, sub-agents, agent-view, agent-teams, workflows, worktrees, cross-session-messaging, best-practices, and commands on 2026-10-25. Claude Code ships fast: confirm anything that matters against the official docs.