$ man how-to/subagents-vs-agent-teams

Claude Code offers two ways to run multiple AI instances on your codebase. Subagents are lightweight workers spawned from your current session. Agent teams are full Claude Code instances that coordinate with each other. The difference is communication and autonomy. Subagents report back to the parent. They cannot talk to each other. They execute a focused task and return results. Think of them as functions you call in parallel. Agent teams communicate with each other. They claim tasks from a shared list. They can message teammates, share discoveries, and coordinate without a central orchestrator. Think of them as an actual team working on the same project.

PATTERN

Subagents are spawned using the Agent tool within a Claude Code session. You specify the task, the agent type (Explore, Plan, general-purpose), and optionally an isolation mode (worktree for separate git branches). Each subagent gets its own context window. It can read files, run commands, search code, and return results. When it finishes, the result comes back to the parent session. Key characteristics: One-way communication. The parent sends a task, the subagent returns a result. No back-and-forth negotiation. Shared filesystem. Subagents see the same repo (unless using worktree isolation). Changes from one subagent are visible to others. Parent orchestration. The main session decides what to delegate, when to spawn, and how to combine results. Cost: each subagent consumes tokens proportional to its task. A quick file search might use 5K tokens. A deep exploration might use 50K. The parent session bears the cost. Best for: parallel research, independent file searches, generating content in parallel, any task where you need speed through parallelism but the tasks are independent.

PATTERN

Agent teams are an experimental feature (enable via CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). One session acts as team lead. It creates tasks in a shared task list. Teammates claim tasks, work on them, and communicate results to each other. Key characteristics: Peer-to-peer communication. Teammates message each other directly. The team lead does not need to relay every piece of information. Shared task system. Tasks are posted to a shared list. Teammates claim tasks based on availability and capability. No central assignment required. Independent context windows. Each teammate has its own full context. They can hold different mental models of the codebase and share discoveries through messages. Higher autonomy. Teammates can discover issues, create new tasks, and coordinate solutions without the team lead directing every step. Cost: each teammate is a full Claude instance. A 3-person team uses roughly 3x the tokens. A 5-person team uses 5x. This adds up fast. Best for: complex multi-module features, parallel code reviews with different focus areas, debugging with competing hypotheses, and any task where agents need to react to each other's findings.

FORMULA

Use subagents when: - Tasks are independent (no task depends on another task's output) - Communication is one-way (send task, get result) - You want the parent session to maintain full control - Budget is a concern (subagents are cheaper) - Tasks are well-defined with clear completion criteria Use agent teams when: - Tasks interact (frontend changes affect backend, shared interfaces) - Agents need to react to each other's discoveries - The problem space is ambiguous and requires exploration - You want agents to challenge each other's approaches - The work would take a single session too long and benefits from true parallelism Use a single session when: - The task is sequential (each step depends on the previous) - The codebase is small enough for one context window - You need tight control over every decision - Cost matters more than speed Real example from my workflow: I use subagents daily for parallel research - "explore the auth module," "find all API endpoints," "check test coverage." These are independent queries. I use agent teams for multi-day features - "build the new dashboard" where one agent handles the API layer, another handles the UI components, and a third writes tests. They need to coordinate on the interface contract between layers.

PRO TIP

Subagents are cheap. A typical explore subagent uses 10-50K tokens. At current pricing, that is pennies. You can spawn 5-10 subagents in parallel without thinking about cost. Agent teams are expensive. Each teammate maintains a full context window that grows with every message and file read. A 3-person team working for an hour can burn through 500K-1M tokens. On API pricing, that is dollars. On Max subscription, it counts against your usage limits. The rule: start with subagents. Upgrade to agent teams only when you hit a real coordination problem that subagents cannot solve. Most tasks do not need agent teams. The single-session-with-subagents pattern handles 90% of parallel work. Another option: multiple terminal tabs, each running an independent Claude Code session on different parts of the codebase. This gives you parallelism without the agent teams overhead. The tradeoff is that sessions cannot communicate - you are the orchestrator.