Claude Code Agent Teams: Multi-Agent Coding Workflows Explained

1. What is Claude Code Agent Teams?

Agent Teams is not a separate product. It is the way Claude Code's native Task tool behaves when an orchestrator agent delegates work to multiple coordinated sub-agents in a single workflow. The name "Agent Teams" refers to this coordination pattern as Anthropic has formalized it in recent Claude Code releases.

The key distinction from running a single agent: an orchestrator in an Agent Team setup does not write code directly. It plans, assigns, tracks progress, and integrates results. The actual implementation, testing, and review work happens in sub-agents — each with its own isolated context window.

This matters because context windows fill up. A solo agent tackling a large codebase refactor will eventually lose track of decisions made in the first hour. By splitting the work across agents, each sub-agent focuses on a narrow slice — say, refactoring one module at a time — while the orchestrator keeps the global view.

2. How the orchestration model works

At the technical level, Agent Teams runs entirely within the Claude Code CLI. There is no separate server, no web dashboard. The orchestrator is a Claude instance running in your terminal with a CLAUDE.md file that defines its role and rules. It spawns sub-agents using the Task tool with a structured prompt.

A sub-agent invocation looks roughly like this from the orchestrator's perspective:

# Orchestrator calls Task tool with:
Task(
  description="Refactor the authentication module",
  prompt="""
    Context: See /src/auth/README.md for module overview.
    Goal: Convert class-based auth handlers to functional pattern.
    Constraints:
      - Preserve all existing test coverage
      - Do not touch /src/auth/middleware.ts (in-progress by another agent)
      - Write a summary of changes to /tmp/auth-refactor-log.md
    Done when: all tests pass, summary written.
  """
)

The sub-agent starts a new Claude session with that prompt, works autonomously on the files, writes its log, and terminates. The orchestrator receives the return value — a structured result summary — and updates the shared task list accordingly.

Sub-agents can be run sequentially (when one depends on the output of another) or in parallel (when tasks are independent). The orchestrator decides. When you invoke multiple Task calls without awaiting the first, Claude Code schedules them concurrently — this is how parallel test runs and parallel review cycles are achieved.

3. Shared task lists and dependency tracking

The "shared task list" in Agent Teams is not a formal data structure built into the CLI. It is a convention — typically a markdown file (often TASKS.md or embedded in MEMORY.md) that the orchestrator maintains and each sub-agent is instructed to read before starting.

# TASKS.md — Managed by orchestrator
## Active
- [ ] auth-refactor: Convert auth module to functional pattern
      ASSIGNED TO: agent-1 | STARTED: 14:23 | BLOCKS: jwt-tests
- [ ] api-types: Generate TypeScript types from OpenAPI spec
      ASSIGNED TO: agent-2 | STARTED: 14:23 | BLOCKS: none

## Blocked (waiting on dependencies)
- [ ] jwt-tests: Update JWT test suite for new auth structure
      DEPENDS ON: auth-refactor | STATUS: waiting

## Completed
- [x] schema-audit: Audit Prisma schema for missing indexes
      COMPLETED: 14:18 | SUMMARY: Found 3 missing indexes, migration written

This file structure gives the orchestrator a durable record of what is in-flight. When an agent completes, it updates the task status. The orchestrator checks TASKS.md before spawning the next batch, which is how dependency ordering works in practice.

It is manual and text-based — there is no built-in lock file or race condition prevention. For most real projects this is fine; concurrent sub-agents are pointed at separate modules to avoid conflicts. File-level overlap requires more careful orchestrator instructions.

4. Real-world use cases

Four scenarios where Agent Teams genuinely outperforms a solo agent:

Large codebase refactors

Migrating a 50k-line monolith from JavaScript to TypeScript is a context-window problem. A single agent loses coherence after the first 20–30 files. Agent Teams handles this by splitting the codebase into module-level chunks: agent-1 converts /src/api, agent-2 converts /src/models, agent-3 handles shared utilities. The orchestrator tracks which chunks are done and queues the next batch. A migration that took a team 3–4 days can run as a supervised overnight Agent Team session.

Parallel test generation

Generating unit tests for an untested module is parallelizable by file. Spawn one agent per major source file, each with instructions to write tests covering the public API, edge cases, and error paths. Parallel execution here cuts wall-clock time significantly — what might take a solo agent 45 minutes (context filling up, slowing down) runs in under 15 minutes with 4 parallel agents.

Code review + auto-fix cycles

This is one of the most practical Agent Teams patterns. Agent-1 reviews a PR diff for security issues, performance problems, and style violations — returning a structured list of findings. The orchestrator passes that list to agent-2, which attempts auto-fixes for items flagged as "safe to automate." Agent-3 then re-reviews the patched diff to confirm fixes landed correctly. Three-agent pipeline; full cycle under 10 minutes for a typical PR.

Cross-repo migrations

When updating a shared library that is consumed by 6 downstream services, agent teams can fan out: one agent per service repo, each updating the dependency and adapting the call sites. The orchestrator aggregates results and flags any repo where the migration failed — usually due to API usage that was non-standard. Human review time shrinks to edge cases rather than the full scan.

5. How we tested

6. Setting up an Agent Team

No special install beyond Claude Code itself. The setup is configuration rather than code.

Step 1 — Write an orchestrator CLAUDE.md

# CLAUDE.md — Orchestrator role

## Identity
You are the orchestrator. You plan and delegate; you do not write code directly.

## Session start
1. Read MEMORY.md (project state) and TASKS.md (active tasks)
2. Identify the next batch of parallelizable tasks
3. Spawn sub-agents via Task tool

## Task assignment rules
- Each sub-agent gets exactly one clearly bounded task
- Include: context files to read, files to NOT touch, expected output location
- Parallel tasks must operate on separate file groups (no overlap)
- Sequential tasks: wait for TASKS.md update before spawning the next

## Session end
1. Update TASKS.md with completed/blocked status
2. Append summary to MEMORY.md
3. Flag any failures for human review

Step 2 — Create TASKS.md with the initial task breakdown for your project. Be specific about file scope per task — vague scope is the most common cause of agent conflicts.

Step 3 — Launch the orchestrator

# In your project root
claude

# Then give the orchestrator its first instruction:
# "Begin the migration session. Read TASKS.md and start the first batch."

The orchestrator reads TASKS.md, identifies parallelizable items, spawns sub-agents, and reports back as they complete. You monitor via the orchestrator's output in the terminal; sub-agent sessions are not visible directly unless you pipe their output to log files (which is worth doing for debugging).

7. Token costs and subscription tiers

This is the part most write-ups gloss over. Agent Teams multiplies your token usage, roughly linearly with the number of parallel agents. An orchestrator session with 3 concurrent sub-agents uses approximately 3–4× the tokens of a solo session on the same task — because each agent has its own input context, each tool call costs, and the orchestrator's meta-coordination adds overhead.

A practical cost-saving tactic: use Haiku 4.5 for sub-agents doing mechanical tasks (type generation, test scaffolding, dependency updates) and reserve Sonnet for the orchestrator and any sub-agent doing reasoning-heavy work. Haiku is roughly 10× cheaper per token and fast enough for retrieval and mechanical transforms.

If cost is a barrier to getting started, group subscription plans through services like GamsGo can reduce Claude Pro costs by 30–50%, which makes the experimentation phase more accessible before committing to Claude Max.

8. Limitations and honest downsides

9. How it compares to alternatives

The multi-agent coding space has several distinct approaches. Claude Code Agent Teams sits in the "terminal-native, developer-controlled" category. Here is how it stacks up against other options:

For a deeper look at how Claude Code itself compares to other IDEs on solo coding tasks, see our Claude Code vs Cursor comparison. For a broader view of how various agentic tools rank across use cases, the agentic AI tools comparison covers 8 frameworks head-to-head.

10. FAQ