Orchestration

Agent teams let you coordinate multiple Claude Code instances working together.

One session acts as the team lead.
Teammates work independently.
Agents have their own isolated context but communicate with each other.
You can interact with any teammate without interacting with the lead.

When to use agent teams:

Investigate different challenges to a problem at the same time.
Independently work on different features that don't overlap.
Work on the same problem but on different theories to see the outcome.
Working on isolated layers, e.g. frontend, backend, tests.

Subagents vs Agent Teams:

Subagents: Main Agent spawns subagents, each does Work → Result, then Reports back to the Main Agent. Use subagents when you need quick, focused workers that report back.
Agent Teams: Main Agent (Team Lead) spawns the team and assigns tasks via a Shared Task List. Teammates communicate & claim tasks from the list, do Work, and can communicate directly with each other. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.

To create an agent team, simply prompt Claude to create one with the shared task, e.g.: "I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate."

An agent team consists of: Team Lead, Teammates, Task List, Mailbox.

Teams and tasks are stored locally:

Team config: ~/.claude/teams/{team-name}/config.json
Task list: ~/.claude/tasks/{team-name}/

Teammates start with the lead's permission settings — if the lead runs with --dangerously-skip-permissions, all teammates do too.