Agent teams

Agent teams are peer sessions that talk to each other and share a task list, as opposed to subagents, which are hub-and-spoke interns that do a task and report back. Reach for a team only when agents genuinely need to coordinate; for independent fan-out, subagents are simpler. For the full decision tree across subagents, teams, and workflows, see Orchestration & Agent Teams.

How you use it day-to-day

• Shared task list. Team members pick up and update a common list, so the work divides without one agent orchestrating every step.
• Message each other. Use SendMessage (by agent id or name) to continue a specific agent with its context intact, rather than starting it fresh.
• Worktree isolation. Give each agent its own git worktree when they edit files in parallel, so they do not collide. A real team-on-one-repo setup adds ownership boundaries and an acknowledge-and-merge step before changes land.

Gotchas

• Coordination is overhead. A team only pays off when agents must agree on something (an interface, a shared file). For "read these ten files and report," that is just parallel subagents.
• No shared memory by default. Members do not see each other's history unless you give them a shared channel or state file. Spell out what each one needs.
• Nesting depth depends on the surface. In the Agent SDK, subagents can spawn their own since Claude Code 2.1.172 (foreground at any depth; a background subagent is capped once it is five levels below the main agent). The interactive CLI Agent tool and the Workflow tool still nest one level only. Design for shallow nesting and go deeper only where the surface you are on supports it.