Parallel, but not the same kind of parallel: How to choose between Claude Code subagents and Agent Teams

This article itself serves as a case study

Before writing this, I used Claude Code to simultaneously task two external LLMs—Codex and Gemini—to look up the differences between subagents and Agent Teams in the official documentation. I then cross-referenced these results with the one generated by Claude itself. I treated the points agreed upon by all three as high-confidence findings, and for any discrepancies, I referred back to the documentation to reach a final conclusion.

This process itself serves as a perfect demonstration of the subagent pattern: a main agent dispatches three subordinates to work independently, then synthesizes their reports. If I had instead used the Agent Teams pattern, they would have communicated with each other and corrected one another’s errors, yielding entirely different results.

Most people actually only understand half of the parallelization in Claude Code.

See the differences at a glance

The fundamental difference in architecture

A subagent is a disposable worker dispatched by the main session. It has its own context but disappears after execution, returning only a single response. The main agent is responsible for coordination and synthesis. This is a star topology.

Each teammate in Agent Teams is another complete Claude Code, on the same level as you. It reads the same project’s CLAUDE.md, skills, and MCP server, but does not inherit your conversation history—it knows only what you provide in the spawn prompt. Teammates communicate via a mailbox at the file system level. This is a mesh topology.

The topology determines what is possible. In a star topology, three reviewers each provide a report that you must integrate yourself; in a mesh topology, if a security reviewer discovers a race condition, they can directly ping the performance reviewer: “Your benchmark may be inaccurate.”

Cost Structure: Why 7×

The official documentation states “Agent Teams in plan mode ~7× tokens.” There are two sources for this:

1. Each teammate consumes its own context: spawning three means three 1M instances are running

2. Coordination messages themselves require tokens: messages in the mailbox must be written into the recipient’s context window

This is why the official documentation repeatedly emphasizes that “Agent Teams are suitable for tasks where coordination itself is the problem.” If your tasks can be cleanly separated so that each subagent works independently, using subagents is always more cost-effective.

When to use which

Practical decision-making framework:

Use subagents if:

• The task can be clearly defined upfront and doesn’t require mid-process dialogue

• You only care about the result, not the process

• Multiple tasks are independent of each other (research, translation, running tests)

• You want to save on context or reduce costs

Use Agent Teams if:

• Findings from multiple teammates affect each other (e.g., security issues impacting performance)

• Long-term interaction is required (continuous debugging, back-and-forth reviews)

• True parallelism is required, and each teammate needs a full 1MB of context

• You have complex dependencies you want to resolve automatically

When in doubt, default to subagents. The 7× cost of Agent Teams is only justified when "coordination itself is the value."

How to use it on Windows

Agent Teams supports two display modes:

• In-process (default): All teammates share your terminal; use Shift+Down to switch. Works in Windows Terminal, cmd, PowerShell, and VS Code terminals.

• Split panes: Each teammate gets their own pane. Only supports tmux or iTerm2. Windows Terminal is not on the supported list.

To use split panes on Windows, the only option is WSL2 + tmux:

# WSL (Ubuntu)
sudo apt install tmux
npm install -g @anthropic-ai/claude-code
tmux
claude

Enable the flag (~/.claude/settings.json）：

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

Recommendation: Don’t switch to WSL just for split panes yet. The in-process mode is fully functional—the only difference is the UX of simultaneous display. Wait until you’ve actually used it once and confirmed you need it before making the switch.

There’s a caveat with Resume

Agent Teams is an experimental feature, and its most significant limitation lies in session restoration:

• /resume and /rewind will not restore teammates in in-process mode—even if the main session resumes successfully, those teammates no longer exist

• After resuming, the lead still holds a reference to the old teammate and may send messages to a non-existent teammate SendMessage

• If this happens, explicitly tell the lead: “That teammate is no longer there; spawn a new one.”

Practical advice: Explicitly shut down important team sessions once they’re complete; don’t rely on resume to continue. Split-pane mode uses tmux to preserve processes, which has fewer limitations, but we still recommend manually reconnecting.

Three Common Pitfalls

1. Two teammates editing the same file: They will overwrite each other. When switching tasks, ensure each teammate has its own set of files

2. Spawn prompt provides too little context: teammates do not inherit the main session’s chat history; they only know what you explicitly provide

3. Tasks split too finely: If three teammates each run a 2-minute task, the coordination overhead ends up exceeding the time it would take to complete everything in a single session

Next Article

The approach used in this article—calling Codex and Gemini within Claude for independent verification—is itself a token-saving pattern. The next post will cover specific configuration details, which tasks should use which external LLM, and why this is more cost-effective than having Claude run the task three times on its own.