7. Decision Framework

Teams vs Multi-Instance vs Dual-Instance

Comparison table:

Criterion	Agent Teams	Multi-Instance	Dual-Instance
Coordination	Automatic (git-based + mailbox)	Manual (human)	Manual (human)
Setup	Experimental flag	Multiple terminals	2 terminals
Best for	Read-heavy tasks needing coordination	Independent parallel tasks	Quality assurance (plan-execute split)
Communication	Peer-to-peer messaging + team lead synthesis	Manual copy-paste	Manual synchronization
Context sharing	Isolated (1M per agent, no auto-sync)	Isolated (separate sessions)	Isolated (2 sessions)
Cost	High (3x+ tokens)	Medium (2x tokens)	Medium (2x tokens)
Cognitive load	Low (observer)	High (orchestrator)	Medium (reviewer)
Merge conflicts	Automatic resolution (limited)	N/A (separate repos)	Manual resolution
Maturity	Experimental (v2.1.32+)	Stable	Stable

Decision Tree: When to Use Agent Teams

Start
  │
  ├─ Task is simple (<5 files)? ──YES──> Single agent
  │
  ├─ NO
  │
  ├─ Tasks completely independent? ──YES──> Multi-Instance
  │
  ├─ NO
  │
  ├─ Need quality assurance split? ──YES──> Dual-Instance
  │
  ├─ NO
  │
  ├─ Read-heavy (analysis, review)? ──YES──> Agent Teams ✓
  │
  ├─ NO
  │
  ├─ Write-heavy (many file mods)? ──YES──> Single agent
  │
  ├─ NO
  │
  ├─ Budget-constrained? ──YES──> Single agent
  │
  ├─ NO
  │
  └─ Complex coordination needed? ──YES──> Agent Teams ✓
                                   ──NO──> Single agent

Use Case Mapping

Agent Teams (✅ Use):

• Multi-layer code review (security + API + frontend)
• Parallel hypothesis testing (debugging)
• Large-scale refactoring (clear boundaries)
• Full codebase analysis (architecture review)
• Complex feature research (explore multiple approaches)

Multi-Instance (✅ Use):

• Separate projects (frontend repo + backend repo)
• Independent features (no shared state)
• Different technologies (Python microservice + React app)
• Parallel experimentation (try 3 different architectures)

Dual-Instance (✅ Use):

• Plan-execute pattern (planning session + execution session)
• Quality review (implementation + code review)
• Test-first development (write tests + implement)

Single Agent (✅ Use):

• Simple implementations (<5 files)
• Write-heavy tasks (shared file modifications)
• Sequential workflows (step-by-step tutorials)
• Budget-constrained projects

Teams vs Beads Framework

Beads Framework (Steve Yegge):

• Architecture: Event-sourced MCP server (Gas Town) + SQLite database (beads.db)
• Coordination: Persistent message storage, historical replay
• Maturity: Community-maintained, experimental
• Setup: Requires Gas Town installation + agent-chat UI
• Use case: On-prem/airgap environments, full control over orchestration

Agent Teams (Anthropic):

• Architecture: Native Claude Code feature, git-based coordination
• Coordination: Real-time git locking, automatic merge
• Maturity: Official Anthropic feature (experimental)
• Setup: Feature flag only (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)
• Use case: Rapid prototyping, cloud-based development

Comparison:

Aspect	Beads Framework	Agent Teams
Control	Full (event sourcing, replay)	Limited (black-box coordination)
Setup	Complex (Gas Town + agent-chat)	Simple (feature flag)
Persistence	SQLite (beads.db)	Git commits
Visibility	agent-chat UI (Slack-like)	Native Claude Code interface
Environment	On-prem friendly	Cloud-first
Maturity	Community-driven	Anthropic official

When to use Beads:

• ✅ On-prem/airgap requirements (no cloud API calls)
• ✅ Need event replay (debugging orchestration)
• ✅ Custom orchestration logic (beyond git-based)
• ✅ Persistent agent communications (audit trail)

When to use Agent Teams:

• ✅ Cloud development (Anthropic API access)
• ✅ Rapid setup (no infrastructure required)
• ✅ Git-native workflows (already using git)
• ✅ Official support path (Anthropic-maintained)

Open question (as of Feb 2026):

"I'm not sure about Claude's guidance on when to use beads versus agent team sessions." Source: Paul Rayner, Feb 2026

Community feedback needed: Anthropic has not published official guidance on this choice. Practitioners are invited to share experiences in GitHub Discussions.