Agent Teams in Claude Code — Native Multi-Agent Orchestration

Claude Opus 4.6 introduces agent teams — the ability to spawn multiple Claude Code agents that work on tasks in parallel within a single session. This is a structural change to how Claude Code operates, not a cosmetic update.

This reference covers what agent teams actually do, when they help, and when you’re better off with external orchestration.

What Agent Teams Are

Before Opus 4.6, Claude Code was single-threaded: one agent, one task, sequential execution. Agent teams allow a primary agent to spawn sub-agents that work concurrently on independent tasks.

Key mechanics:

• Sub-agents operate in their own context but share the same filesystem
• The primary agent coordinates: assigns tasks, collects results, synthesizes
• Navigation between agents via Shift+Up/Down or tmux panes
• Agents coordinate autonomously — you don’t manually route messages between them

When Agent Teams Help

Agent teams provide clear wins for tasks that are:

Parallelizable and read-heavy:

• Analyzing multiple files or modules simultaneously
• Running different research queries in parallel
• Reviewing a PR while another agent runs tests
• Searching for patterns across different parts of a large codebase

Independent with a shared goal:

• “Agent A: analyze the backend API. Agent B: analyze the frontend components. I’ll synthesize both.”
• “Agent A: find all usages of this deprecated function. Agent B: write the replacement implementation.”

When Agent Teams Don’t Help

Sequential dependencies: If step 2 needs step 1’s output, parallelism adds overhead without benefit. A single agent executing sequentially is simpler and often faster.

Write-heavy tasks on the same files: Multiple agents editing the same file will create conflicts. The filesystem is shared but there’s no locking mechanism. If two agents both modify src/config.ts, you get a race condition.

Small tasks: Spawning a team for a one-file fix is overhead. The coordination cost exceeds the parallelism gain.

Tasks requiring deep context: Each sub-agent has its own context window. It doesn’t share the primary agent’s full conversation history. If the task requires understanding a nuanced decision made earlier in the session, the sub-agent starts cold.

Agent Teams vs. External Orchestration

If you’ve built orchestration infrastructure — a workflow engine that dispatches Claude Code tasks via HTTP API — you now have two options for multi-agent work. They solve different problems.

Native Agent Teams

You ←→ Primary Claude Code Agent
              ├── Sub-agent A (same machine, same filesystem)
              ├── Sub-agent B
              └── Sub-agent C

Strengths:

• Zero setup — built into Claude Code
• Shared filesystem — agents see each other’s changes in real-time
• Interactive — you can observe and redirect agents mid-task
• Context-aware — primary agent understands the high-level goal

Limitations:

• All agents run on the same machine
• No persistence — team disbands when session ends
• No scheduling — can’t trigger teams on cron or events
• Limited to Claude Code’s tool set — no custom workers

External Orchestration (Workflow Engine)

Workflow Engine (e.g., Obi)
  ├── Step 1: HTTP worker (fetch data)
  ├── Step 2: Claude Code worker (analyze)
  ├── Step 3: LLM worker (extract structured output)
  └── Step 4: HTTP worker (POST results)

Strengths:

• Heterogeneous workers — mix Claude, LLMs, HTTP, custom workers
• Persistent — workflows survive beyond any single session
• Schedulable — cron, event-driven, API-triggered
• Cost-efficient — route simple tasks to cheaper workers, reserve Claude for agency tasks
• DAG execution — complex dependency graphs with fan-out and fan-in

Limitations:

• Setup cost — need a workflow engine
• No shared filesystem — workers communicate via data passing
• No interactive observation — fire and forget, check results later

Decision Framework

The two approaches compose. You can use agent teams for interactive work during a session and external orchestration for everything that needs to run unattended.

Practical Patterns

Pattern 1: Parallel Code Review

Primary: "Review this PR for correctness and performance issues."
  Agent A: Reviews the backend changes (API routes, database queries)
  Agent B: Reviews the frontend changes (components, state management)
  Agent C: Runs the test suite and reports failures
Primary: Synthesizes all three reports into a unified review.

This works well because each agent operates on different files and produces independent analysis.

Pattern 2: Research + Implementation Split

Primary: "Add OAuth2 support to our authentication system."
  Agent A: Research — reads existing auth code, identifies integration points
  Agent B: Research — checks dependencies, finds OAuth2 library options
Primary: Makes architectural decision based on both reports.
  Agent C: Implements the chosen approach
  Agent D: Writes tests for the new auth flow

The research phase parallelizes perfectly. Implementation becomes sequential once decisions are made.

Pattern 3: Multi-Module Debugging

Primary: "Users report slow page loads after the last deploy."
  Agent A: Profiles the API response times (backend)
  Agent B: Analyzes the frontend bundle size and network waterfall
  Agent C: Checks database query performance (slow query logs)
Primary: Correlates findings, identifies root cause.

Each agent investigates one layer of the stack independently. The primary agent’s job is synthesis, not investigation.

Constraints to Be Aware Of

Cost multiplication: Each sub-agent consumes its own tokens. A team of 4 agents uses roughly 4x the tokens of a single agent. For Max Plan users this may not matter. For API users, it scales linearly.

Context fragmentation: The primary agent has full session context. Sub-agents don’t. If you’ve spent 30 minutes building up context about a tricky architectural decision, a newly spawned sub-agent doesn’t know any of that unless you explicitly pass it in the task description.

Filesystem races: No locking. Two agents writing to the same file will cause silent overwrites. Design task decomposition so agents operate on disjoint file sets.

Observation overhead: More agents means more activity to monitor. Without clear task boundaries, the benefit of parallelism gets lost in the cognitive cost of tracking what each agent is doing.

The Bigger Picture

Agent teams move Claude Code from “a smart assistant that does one thing at a time” to “a team you can direct.” This is a significant capability jump for interactive work.

But for automated, recurring, persistent workflows — the kind that run while you sleep — external orchestration remains the right architecture. Agent teams are session-bound. Orchestration engines are infrastructure.

The optimal setup: use agent teams for interactive exploration and decision-making during your work sessions. Use orchestration for everything that needs to run without you.