Skip to main content
Official reference — The official Agent Teams docs cover setup, architecture, keyboard shortcuts, display modes, and limitations. This page adds the decision framework and practical advice.
Agent Teams is experimental. Expect rough edges — no session resumption, occasional task status lag, and slow shutdown.

​
When to Use Agent Teams

Use this decision framework:
SituationToolWhy
Fully independent work (migrations, convention enforcement)/batchNo coordination overhead, cheapest option
Tasks that report results back (research, analysis)SubagentsParent orchestrates, ~4-7x cost
Tasks that need to discuss and coordinateAgent TeamsShared task list + messaging, ~15x cost
Agent Teams justifies its ~15x token cost only when agents genuinely need to share findings, challenge each other’s assumptions, or self-coordinate through a shared task list.

​
Delegate Mode Is Essential

Press Shift+Tab to cycle into delegate mode, which restricts the lead to coordination-only tools.
Without delegate mode, the lead frequently implements tasks itself instead of delegating. Practitioners consistently flag this as the most common Agent Teams failure mode.
In delegate mode, the lead can only:
  • Create and manage tasks
  • Send messages to teammates
  • Review and approve plans
  • Synthesize results

​
A Typical Session

You: "Create a team for the auth refactor"
Lead: Creates team, spawns 3 teammates:
  - backend-auth (implements API changes)
  - frontend-auth (updates UI components)
  - auth-tests (writes integration tests, blocked by backend-auth)

You: Enable delegate mode (Shift+Tab)
Lead: Creates tasks, assigns to teammates
Teammates: Work independently, message each other when interfaces change
You: Monitor with Ctrl+T, review output as teammates complete
Lead: Synthesizes results, resolves conflicts

​
Practical Advice

  • Sweet spot: 3-5 teammates. Fewer underutilizes parallelism; more creates coordination overhead exceeding the throughput gain.
  • Use plan approval for high-stakes work — teammates submit plans before implementing, the lead reviews.
  • Prepare for no session resumption. If you need to /resume, tell the lead to spawn replacement teammates.
  • Nudge on task status lag. Teammates sometimes forget to mark tasks complete — check with Ctrl+T.
← Prev: Permutation Frameworks · Next: Permission Modes →