Claude Code agent teams vs subagents: when to use which

Claude Code agent teams are several Claude Code sessions working on one task: a lead session spawns teammates, each with its own context window, and they share a task list and message each other directly. Subagents are lighter: workers inside your session that do one job and report back a summary. As of October 2026, agent teams are experimental and off by default; you turn them on with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable. Anthropic's rule of thumb: use subagents for quick, focused workers that report back, and agent teams when teammates need to share findings, challenge each other and coordinate on their own.

Key takeaways

• Agent teams have been experimental since February 5, 2026, and run in the terminal, not in the desktop app.
• They use about seven times the tokens of a standard session when teammates run in plan mode. Anthropic suggests three to five teammates.
• Subagents are built in, count toward the same usage limits as your main conversation, and can nest three layers deep by default.
• Custom slash commands were merged into skills in January 2026. Skills run in your main context; subagents run in their own.
• Both are one person's tools: nobody else can join your team or your session.

How do you turn on agent teams?

1. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell, or under env in settings.json (docs).
2. Start an interactive session in the terminal. Teammates don't spawn in non-interactive runs (-p) or through the Agent SDK.
3. Ask for a team in plain language, for example: "Spawn three teammates to review PR #142, one on security, one on performance and one on test coverage."

While teams are on, any subagent Claude names starts as a teammate, so a team can form without you asking for one.

How do agent teams work?

• The lead is your main session, for the team's whole life. Leadership can't be handed over.
• Teammates are separate Claude Code sessions with their own context windows. They load CLAUDE.md, MCP servers and skills, but not the lead's conversation.
• A shared task list tracks pending, in-progress and completed tasks, with dependencies. The lead assigns tasks or teammates claim them, and file locking stops two claiming the same one.
• Messages go from one agent to another by name, delivered automatically.
• Display: by default all teammates run inside your terminal, and you select one in the agent panel to talk to it directly. Split panes need tmux or iTerm2, and don't work in VS Code's integrated terminal, Windows Terminal or Ghostty.

What are the limits?

• /resume and /rewind don't bring back in-process teammates.
• One team per session, no nested teams, and a team can't be shared across sessions.
• Permissions are set when a teammate starts.
• Teammates don't get separate worktrees, so split the files between them yourself or they'll edit the same one.
• Task status can lag, and shutting a team down can be slow.

What do agent teams cost?

Anthropic says agent teams use "approximately 7x more tokens than standard sessions when teammates run in plan mode," and that usage grows with each active teammate and how long it runs (costs). Its advice: use Sonnet for teammates, keep teams small, keep spawn prompts focused, and shut teammates down when they're done. On a subscription, that comes out of the same five-hour and weekly limits (Claude Code usage limits).

What are subagents?

A subagent runs in its own context window with its own system prompt, tools and permissions, and returns only a summary to your conversation (docs). The full guide is Claude Code subagents.

• Built in: Explore (read-only search), Plan (read-only research in plan mode) and a general-purpose agent with every tool.
• Your own: Markdown files in .claude/agents/ for a project or ~/.claude/agents/ for you, with a name and description, plus optional tools, model, permission mode, skills, MCP servers, hooks, memory and worktree isolation.
• Nesting: a subagent can start its own, up to three layers below your conversation by default.
• Usage: each subagent's requests count toward the same usage limits as your main conversation.

Good uses, from Anthropic's docs: run the test suite and report only the failures, or research three modules in parallel without filling your context.

Subagents vs skills vs slash commands

Custom slash commands were merged into skills on January 9, 2026: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy (docs). The built-in ones are listed in Claude Code slash commands.

• A skill is reusable instructions, knowledge or a workflow. It runs in your main context, so you see and steer each step. Anthropic's feature overview: it "adds to your main window."
• A subagent is an isolated worker. It "uses a separate window" and hands back a result (overview).

If you keep typing the same prompt, make it a skill. If a side task floods your conversation, give it to a subagent. They combine: a subagent can preload skills, and a skill can run in a subagent.

Agent teams vs Claude Code projects

Claude Code's projects, in beta since September 17, 2026 on Pro and Max, are the longer-lived cousin: a coordinator conversation starts parallel threads, each a cloud session on its own branch with shared project memory (docs). An agent team is one session that starts teammates for a single task and ends with it.

Can several people use one agent team?

No. The lead's terminal is the only human seat, teammates' permission prompts come back to it, and a team can't be shared across sessions. Projects belong to one user too. Agent teams are multi-agent, not multiplayer: more AIs, still one person (the difference).

For several people steering one agent, Anthropic's own option is Claude Tag in Slack, on Team and Enterprise (What is Claude Tag?). Poly (usepoly.co) is a browser room where a team works with one Claude Code agent together: everyone sees each step live, and any member can approve a change before it happens. Free to start. What is Poly?