Claude Code Agent Teams: When Sub-Agents Aren't Enough

Sub-agents are great for one thing: a quick, isolated job that reports back once. Spin one up, it does the work, it tells you what it found, done. But the moment a task actually needs multiple perspectives talking to each other — challenging findings, dividing up ownership, coordinating on their own — that one-way report-back model just doesn't hold up.

That's the gap Agent Teams (experimental, currently) close. A team lead spawns teammates that can message each other, share a task list, and push back on each other's work before anything comes back to you.

When to actually reach for this#

Not every job needs a team. It's worth it when:

• Parallel exploration — multiple genuinely distinct angles add value: one agent on UX, one on architecture, one deliberately playing devil's advocate.
• Complex debugging — testing several hypotheses at once to find the root cause faster.
• Distinct feature ownership — agents each own a separate file or folder without stepping on each other.
• Cross-layer coordination — a change spans frontend, backend, and tests, and each layer needs a dedicated owner.
• Peer review — the same PR reviewed simultaneously from different lenses: security, performance, accessibility.
• Real inter-agent collaboration — workers genuinely need to message each other and self-coordinate.

For anything simpler than that, a regular sub-agent is still the right call.

The architecture#

• Team lead — the main session. Creates the team, spawns the teammates, coordinates the work.
• Teammates — separate Claude Code instances, each working an assigned piece.
• Shared task list — the work items teammates claim and complete.
• Mailbox — the internal messaging system teammates use to talk to each other.

Each teammate gets its own context window. When spawned, it loads the same project context you'd get in a regular session — CLAUDE.md, MCP servers, Skills — plus the specific spawn prompt from the lead.

In the video#

• 00:00 — Sub-agents vs. agent teams: where the one-way report-back model breaks down
• 01:51 — The architecture: lead, teammates, shared task list, mailbox
• 03:06 — Setting up a real team: three agents attacking one CLI tool from different angles (dev experience, architecture, packaging strategy)
• 06:32 — Enabling the experimental flag in settings.json — this feature is off by default
• 07:29 — Running it live, navigating between agents with Shift+Up/Down

Setting one up#

Enabling it takes one flag. In settings.json:

{
  "environment": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

From there, you just tell Claude to create an agent team and describe the angles you want covered. In the video, the goal is a CLI that generates MCP documentation servers from a sitemap — and the team gets three assigned angles: developer experience, technical architecture, and packaging/publishing strategy. You can pin a specific model per agent, require plan approval before any teammate makes changes, and — worth calling out specifically — turn on delegate mode, so the team lead only orchestrates and responds to findings instead of also grabbing tasks off the shared list itself.

What it's actually like right now#

Once it's running, you navigate between the live agents with Shift and Up/Down, watching each one work its angle. It's genuinely useful for getting a problem attacked from angles you wouldn't have thought to check yourself — but it's an experimental feature, and it shows: you're still babysitting each agent's progress rather than firing it off and walking away.

The actual point#

Reach for a sub-agent when you need a quick, focused answer and nothing more. Reach for an agent team only when the job genuinely needs teammates that talk to each other — parallel angles on one hard problem, or ownership split cleanly across layers. Anything less than that, and you're just paying the coordination overhead for no reason.