Claude Code agent teams vs subagents: when to use each, and how to set up a team

Agent teams vs subagents

Both run work in parallel in separate context windows. The difference is who coordinates: with subagents the main agent manages everything; in a team, teammates claim tasks from a shared list and talk to each other.

When to use agent teams (and when not to)

• Research and review: teammates look at a problem from different angles, then challenge each other's findings.
• New modules or features: each teammate owns a separate piece, such as frontend, backend and tests.
• Debugging with competing hypotheses: several teammates each try to prove their theory and disprove the others'.
• Not for sequential work, edits to the same files, or tasks with many dependencies: use one session or subagents there.
• Not for routine work: token use grows with every active teammate.

How to set up a Claude Code agent team

1. Turn agent teams on

   Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or in the env block of settings.json. Teams need an interactive session; with -p (and the Agent SDK) Claude doesn't spawn teammates.

   // settings.json: agent teams are experimental and off by default
   {
     "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" }
   }
   
   // Optional: give each teammate its own split pane (tmux or iTerm2)
   {
     "teammateMode": "auto"
   }

2. Describe the team in plain language

   Say how many teammates and what each one does. Claude creates the shared task list, spawns them and synthesizes their findings when they finish.

   Spawn three teammates to review PR #142:
   - One focused on security implications
   - One checking performance impact
   - One validating test coverage
   Have them each review and report findings.

3. Pick a display mode

   In-process is the default and works in any terminal: teammates appear in a panel under the prompt; use the arrow keys and Enter to open one and message it, and Ctrl+T for the task list. Split panes give each teammate its own pane and need tmux or iTerm2 with the it2 CLI; set teammateMode to auto or tmux, or start with claude --teammate-mode auto.

4. Reuse roles you already defined

   Ask for a teammate "using the security-reviewer agent type" to reuse a subagent definition from .claude/agents/, with its tools, model and instructions.

5. Steer, then shut down

   Check in on teammates, redirect them, and say "wait for your teammates" if the lead starts doing their work. To finish, ask the lead to shut a teammate down by name; the team's directories are cleaned up when the session ends.

Source: Claude Code docs, Agent teams

Best practices and limitations

• Start with 3–5 teammates and about 5–6 tasks each; three focused teammates often beat five scattered ones.
• Give each teammate a different set of files: two teammates editing the same file overwrite each other.
• Put task details in the spawn prompt: teammates load CLAUDE.md, MCP servers and skills, but not the lead's conversation.
• Use hooks as quality gates: TeammateIdle, TaskCreated and TaskCompleted can send work back with exit code 2.
• Limits: one team per session, no nested teams, the lead can't change, /resume doesn't bring back in-process teammates, and task status can lag.
• Split panes don't work in VS Code's integrated terminal, Windows Terminal or Ghostty; in-process mode works everywhere.
• With agent teams on, a subagent Claude names can launch as a teammate; set the variable to 0 if you want plain subagents back.

Agent teams vs other ways to run Claude Code in parallel

Agent teams split one task you're watching, inside one session. For independent tasks, run separate sessions in git worktrees or as background agents; for a full comparison, read multiple Claude Code agents. To keep the cost down, see how to reduce Claude Code token usage.

A team that keeps working after the session ends

An agent team lives inside one session and stops when you close it. Crewmark turns Claude Code, Codex, DeepSeek Harness or OpenCode sessions into AI employees with lasting roles, goals and working hours: each wakes on a heartbeat, takes the next issue from a shared board and messages you when it needs a decision.

1. Give each employee a role

   A software engineer, a reviewer, an SEO specialist: the roles you'd spawn as teammates, kept for good.

2. Work from one board

   Issues replace the session's task list, and they survive restarts, days and weeks.

3. Let the heartbeat start the work

   Every 15, 30 or 60 minutes during working hours; see what an AI employee is.

Claude Code agent teams FAQ