agent-teams

Agent Teams Orchestration (Experimental)

Status: Experimental — OFF by default (requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) When to use: Large features where multiple teammates can work truly in parallel and the user explicitly accepts the token cost

What Are Agent Teams?

Agent Teams are coordinated background sessions with a shared task list, inter-agent messaging, and a lead/manager that assigns tasks and keeps workers in sync. Instead of the Orchestrator calling agents sequentially via Task tool, a lead agent dispatches work and teammates claim, execute, and report tasks from the shared queue independently.

This surface is experimental and off by default — enable it only by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment or settings.json.

How This Relates to the Other Parallelization Surfaces

GodMode maps onto four parallelization surfaces. Choose the right one for the job:

Decision guidance:

• Use plain subagents for one-off in-session side tasks (the default, always available).
• Use agent teams when you need persistent, coordinated teammates kept in sync via a shared task list across a multi-part project.
• Use dynamic workflows when a job outgrows a handful of subagents and needs fan-out at scale plus adversarial verification — trigger with the word "workflow" in a prompt or enable ultracode.
• See also the ## Parallelization section of CLAUDE.md for the cost guardrail and concurrency tiers that apply across all surfaces.

Enabling Agent Teams

Add to your environment or settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Team Composition

Recommended team size: 3–5 teammates for optimal coordination.

SharedTaskList

Tasks follow this lifecycle:

pending → in_progress → completed
                     → failed

• Dependencies: Tasks can have blockedBy arrays
• Claiming: File-locking prevents race conditions
• Auto-pickup: After completing a task, teammate picks next unblocked task

Example Task Flow

{
  "tasks": [
    {"id": "1", "name": "Design auth module", "assignee": "architect", "status": "completed"},
    {"id": "2", "name": "Implement auth API", "assignee": "builder", "blockedBy": ["1"], "status": "in_progress"},
    {"id": "3", "name": "Implement auth UI", "assignee": "builder", "blockedBy": ["1"], "status": "in_progress"},
    {"id": "4", "name": "Validate auth code", "assignee": "validator", "blockedBy": ["2", "3"], "status": "pending"},
    {"id": "5", "name": "Test auth UX", "assignee": "tester", "blockedBy": ["2", "3"], "status": "pending"}
  ]
}

Hooks for Agent Teams

When to Use Agent Teams vs Standard Orchestration

Limitations

• No session resumption with in-process teammates
• Task status can lag
• Only one team per session
• No nested teams
• Token usage: ~15x standard
• Shutdown can be slow

Use skills/departments/ first when the problem is ownership and routing. Use Agent Teams only when the implementation work itself can safely run in parallel.

Best Practices

1. Break work into truly independent tasks
2. Define clear dependencies with blockedBy
3. Keep team size to 3–5 teammates
4. Use worktree isolation for all building/testing teammates
5. Reserve standard orchestration for sequential workflows (API changes)