Advanced12 min
Spawning and Coordinating a Team
You do not pre-configure agent teams — you describe what you need and the Lead orchestrates. This article walks through the runtime patterns for spawning, assigning work, monitoring progress, and merging teammate output.
Quick Reference
- →Teams are created at runtime via natural language — no pre-configuration needed
- →Reference AGENT.md definitions when spawning: 'Spawn a teammate using the security-reviewer agent type'
- →Each teammate must own distinct, non-overlapping files — conflicts overwrite work
- →Sequential handoffs use the Shared Task List as a dependency chain
- →Parallel independent work: multiple teammates, each owning different files, no coordination needed
- →Teammates auto-notify the lead when idle — use this to monitor and reassign
- →Team config is auto-generated at ~/.claude/teams/{team-name}/ — do not pre-author it
- →Known limitation: no nested teams — only the Lead can spawn teammates
Spawning a Team at Runtime
Agent teams are not pre-configured — they are created dynamically when you ask for them. Describe the team you need and the Lead Claude Code session handles the spawning. You can reference your AGENT.md definitions to use existing specialist configurations.
Team Config Is Auto-Generated
Claude Code creates ~/.claude/teams/{team-name}/config.json automatically when you spawn a team. Do not pre-author this file — it is managed by Claude Code and contains runtime state that changes as the team works.