Claude Code Agent Teams

I. TL;DR

II. Executive Assessment

What It Is

A Claude Code session acts as “team lead” and spawns independent teammates, each running as a full Claude instance with its own context window. Teammates communicate directly with each other through messages and coordinate via a shared task list. Unlike subagents (which are fire-and-forget workers reporting results back), teammates can discuss, challenge, and build on each other’s work mid-task. Enabled with one environment variable: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Announced Feb 5, 2026 alongside Opus 4.6.¹

Readiness Assessment

Applicability to Eric’s Stack

Bottom Line Before Deep Dive

III. Architecture Deep Dive

Mental Model

Agent Teams uses a flat peer-to-peer topology. One session acts as team lead (spawns teammates and synthesizes results), but teammates communicate directly with each other — there is no hierarchy beyond the lead’s spawn privilege. All agents share the same filesystem (git repository).

┌─────────────────────────────────────────────┐
│                 TEAM LEAD                     │
│  (orchestration, task assignment, synthesis)  │
│                                               │
│  Shared Task List ↔ All teammates read/write │
│                                               │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │Teammate A│↔│Teammate B│↔│Teammate C│   │
│  │(frontend)│  │(backend) │  │(tests)   │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│       ↕              ↕              ↕         │
│            Shared Git Repository              │
└─────────────────────────────────────────────┘

The flat structure means any teammate can message any other teammate directly. The lead doesn’t relay messages — it orchestrates task assignment and collects final outputs. The shared filesystem (git repo) is the implicit coordination layer: all agents read and write files in the same directory tree.

Key Mechanisms

1. Spawning. The team lead creates teammates via natural language. Each gets its own context window, its own tool permissions, and its own conversation history. Teammates are spawned with a specific task description that scopes their work. The lead can spawn as many teammates as needed, though practical limits emerge around 4–6 due to coordination overhead.¹

2. Communication. Three channels exist: (a) direct messages between any two agents, (b) broadcast from lead to all teammates, and (c) a shared task list readable and writable by all. Messages are file-based — each agent has an inbox file on disk, with JSON entries carrying read/unread flags. This is the fragile part: message delivery bugs are the #1 reported issue. In VS Code, teammate messages never surface to the team lead. In tmux on macOS, teammates never poll their inbox files.^2,3

3. Task List. A shared data structure that any teammate can read, claim, and update. The lead uses it to track progress and reassign work. Tasks should be sized at 5–6 per teammate for optimal coordination — too few and agents idle waiting; too many and context thrashing eats the gains.⁴

4. Delegate Mode. Activated by pressing Shift+Tab. Restricts the lead to coordination only — no code writing. This is critical for setups with 4+ teammates: without delegate mode, the lead gets pulled into implementation details and stops coordinating. The result is a traffic jam where teammates block on the lead’s attention.⁹

Subagents vs Agent Teams

Under the Hood

Each teammate runs as a separate Claude Code process. Communication happens via inbox files on disk — JSON files with read/unread flags that agents poll periodically. The shared filesystem is a shared git repository: all agents push and pull from the same working tree.

In Carlini’s 16-agent compiler project, the setup was 16 Docker containers sharing a git repo, with lock files for task claiming to avoid race conditions.⁷

Token consumption scales with team size. Each teammate loads full project context + conversation history + messages from other agents. For a 3-agent team on a medium project, expect 300K–500K tokens per session. The messaging overhead alone can account for 15–20% of total tokens, as every message is re-read on each polling cycle.

IV. Real-World Constraints

Known Limitations

• No session resumption — if a teammate crashes, work is lost¹
• No nested teams — can’t spawn sub-teams¹
• Task completion tracking unreliable¹
• Slow shutdown — agents don’t cleanly terminate¹
• File conflicts when teammates edit same files⁴
• Spawned agents don’t inherit main Claude’s permissions — repeated permission prompts cause deadlocks⁵

Cost Analysis

Failure Modes

Observed failure patterns from Reddit and GitHub issue reports:

• Deadlock: Agent asks for permission, prompt invisible in VS Code, agent stuck forever²
• Quality degradation: One user tested the same app twice — Agent Teams was faster (5 vs 7 min) but needed more manual fixes because “agents weren’t fully aware of full context”¹⁴
• File conflicts: Two teammates edit same file → overwrites and lost work⁴
• Workaround: --dangerously-skip-permissions flag, but security tradeoff⁵

Production Readiness

V. Practitioner Discourse

What Practitioners Are Saying

Success stories:

• Nicholas Carlini: 16 agents built a 100K-line C compiler in Rust that compiles Linux. The most ambitious agent teams demo to date. But conditions were ideal: well-defined spec (C standard), comprehensive test suite (GCC torture tests), independent compilation units. Real projects rarely have these properties.⁷
• Mejba Ahmed: Built the same task manager app twice. Agent Teams version was faster (5 vs 7 min) and “architecturally deeper, more feature-complete.” But required more manual cleanup.¹⁴
• Daniel Avila: Successfully used Agent Teams for multi-file debugging — splitting console.log cleanup across file ownership boundaries.¹⁵

Failure stories:

• Rails-to-Next.js migration: Developer reported Agent Teams were faster but quality suffered — “agents weren’t fully aware of full context” and required numerous manual fixes. Single session produced better results with less cleanup.⁶
• Permission deadlocks: Multiple users report spawned agents stuck waiting for permission approval that’s invisible in VS Code. Only workaround is --dangerously-skip-permissions.⁵

Workarounds practitioners use:

• Use terminal (not VS Code) to avoid message delivery bugs²
• --dangerously-skip-permissions or sandbox with auto-allow bash⁵
• Explicit file boundaries in spawn prompts to prevent conflicts⁴
• Keep teams to 2–3 agents max for reliability⁴

Sentiment Summary

VI. Critical Assessment

The Hype

“16 agents built a C compiler!” is the headline. Anthropic shipped Agent Teams alongside Opus 4.6 — the message is clear: this is the future of AI-assisted development. The community is excited about “directing a team” instead of “prompting a tool.”

Adversarial Challenges

Hype vs Reality

Honest Timeline

VII. Implementation Guide

Prerequisites

• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Anthropic API key or Max subscription
• Terminal-based workflow recommended (VS Code has messaging bugs)
• Recommended: tmux or iTerm2 for split pane mode (but note tmux inbox polling bug)

Quickstart

1. Enable:

   export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

2. Start Claude Code in your project:

   claude

3. Prompt with team structure:

   “Create a team: one agent for the API routes in src/api/,
   one for the React components in src/components/,
   one for tests in tests/.
   Each owns their directory exclusively.”

4. Use Shift+Tab to enter delegate mode (lead coordinates only)
5. Use Shift+Up/Down to navigate between teammates
6. Monitor the shared task list for progress

First Real Project

Gotchas

1. VS Code extension has messaging bugs — use terminal instead²
2. Spawned agents don’t inherit permissions — either use --dangerously-skip-permissions or configure allowlists in advance⁵
3. NEVER let two teammates edit the same file — explicit ownership in spawn prompts⁴
4. Compact/context window discipline applies PER teammate — each burns through context independently¹³
5. No session resumption — if your laptop sleeps or network drops, teammate work may be lost¹
6. Agent Teams is 2× the cost of single-session — only use for genuinely parallel work¹⁰

Resources

• Official docs: code.claude.com/docs/en/agent-teams — adequate, covers basics¹
• Best tutorial: claudefast complete guide — most thorough community resource⁴
• Community: r/ClaudeCode subreddit — active, real problems discussed^5,6
• Controls reference: claudefast controls guide — delegate mode, hooks, display modes⁹
• Reference project: Carlini’s C compiler blog post — ceiling demo, not template⁷

VIII. Verdict & Recommendations

Technology Verdict

Specific Recommendations for Eric

Try first  Donna multi-tenant build. Three channel adapters (WA, Telegram, email) are independent file sets. Spawn 3 teammates, one per adapter. Test on next Donna sprint. If it works, this becomes the template for all multi-adapter builds.

Second experiment  Wenhao blue-collar app. Frontend + backend + vision pipeline split is natural. But coordinate via git — don’t rely on Agent Teams messaging (use the Carlini pattern: shared repo, lock files).

Skip  Sourcy / research / PCRM. Sequential work. Single session or Cursor Task subagents are better.

What Would Change the Verdict

• Upgrade to ADOPT if: Message delivery bugs fixed + session resumption added + VS Code support stable. Monitor GitHub issues #25254 and #23415.
• Downgrade to HOLD if: Bugs persist >3 months, or Anthropic deprioritizes the feature (signals: no updates to docs, issues go stale).

Next Steps

1. Enable Agent Teams in terminal (not VS Code): export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 — 5 minutes
2. Run one bounded experiment on Donna adapter split: 2 hours max
3. Document what works and what breaks in crm/notes/ — 15 minutes
4. Share findings with Penny (she’ll have complementary perspective) — async
5. Monitor GitHub issues for message delivery fix — ongoing, check weekly

IX. Open Questions

• Will Anthropic prioritize fixing message delivery for VS Code, or push terminal-first?
• How does Agent Teams interact with MCP tool servers — can teammates share tool connections?
• What’s the token efficiency curve — at what team size does coordination overhead exceed parallelism gains?
• Can Agent Teams be combined with Cursor’s Task subagents for a hybrid approach (lead in Cursor, teammates as Claude Code instances)?
• When Penny says “going to be out of a job” — is she reacting to Agent Teams specifically or the broader multi-agent trajectory?