Claude Code · concept explainer

Agents vs Teams

Two different ways Claude Code orchestrates work. Agents are lightweight specialists that report back to you inside one session. Teams are independent full sessions that talk to each other and coordinate through a lead.

Agents (Subagents)
Workers inside your session.
Spawned for a task, given their own context window + tool set, and return a single result to you.
Agent Teams · experimental
Independent sessions that collaborate.
Each teammate is a full Claude Code session. They message each other and coordinate through a lead.

How the wiring differs

Look at the arrows — that is the real difference.

Agents hub & spoke

You are the hub. Each subagent talks only to you. They never see each other.

You
Main session
Explore
read-only
Plan
read-only
Reviewer
specialist
General
multi-step
request → result (returns to you)

Teams mesh + lead

You talk to the lead. The lead and teammates message each other directly. Each is a full session.

You
Operator
Lead
coordinator
Security
teammate
Perf
teammate
Tests
teammate
direct messaging (solid = with you/lead, light = peer-to-peer)

Side-by-side

The properties that actually matter when you're deciding which to reach for.

Property Agents (Subagents) Agent Teams
What it is A specialized worker spawned inside your main session. A collection of independent Claude Code sessions that coordinate.
Context window Its own — does ✕not see your conversation history. Each teammate has its own full session window.
Communication Returns one result to you. Subagents never see each other. Teammates message each other directly + the lead.
Configured in .claude/agents/ (project)
~/.claude/agents/ (user) 		~/.claude/teams/{name}/config.json
Enabled by env flag (see below).
How you invoke "Use the code-reviewer agent…" or @code-reviewer "Create an agent team to review PR #142 — spawn three reviewers…"
Parallelism ✓ Multiple at once, foreground or background. ✓ Full sessions in parallel; viewable in split-panes (tmux/iTerm2).
Cost profile Lightweight — one extra context per agent. Heavier — each teammate is a full Claude Code session.
Built-ins Explore, Plan, general-purpose, statusline-setup, claude-code-guide, … No fixed roster — you describe the team and it spawns teammates (can reference agent types).
Stability ✓ GA — stable, widely used. ⚠ Experimental, off by default. Known rough edges around resume/shutdown.

Setup, side by side

A subagent definition is a markdown file. A team is unlocked with one env flag.

Define a subagent .claude/agents/code-reviewer.md 
---
name: code-reviewer
description: Expert code review specialist.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer.
Focus on correctness, security, and
clarity. Return a punch list.
Enable agent teams ~/.claude/settings.json 
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

// then, inside Claude Code:
// "Create an agent team to review
//  PR #142. Spawn three teammates:
//  security, performance, tests."

When to reach for which

The decision usually comes down to: do the workers need to talk to each other?

Reach for an Agent when…

  • You want to protect your main context from a noisy search or large file scan.
  • You need a specialist with a narrow prompt (reviewer, planner, explorer).
  • You want to run several lookups in parallel and merge the results yourself.
  • The work is one-shot: spawn, get answer, done.
  • You want a reusable, version-controlled definition checked into the repo.

Reach for a Team when…

  • The workers need to talk to each other, not just to you.
  • You want a lead to delegate, gather, and synthesize across teammates.
  • The task spans multiple independent surfaces (e.g., security + perf + tests on one PR).
  • You're okay with higher token cost in exchange for richer collaboration.
  • You're comfortable with experimental behavior and split-pane viewing.

TL;DR

Agents are specialists you delegate to — they report back to you and never see each other. Teams are independent sessions that coordinate — they message each other through a lead and operate in parallel.

Heads-up: "Teams" in Claude Code is not a billing tier or org/workspace feature — it's an experimental multi-agent orchestration mode. It doesn't share settings across humans; it orchestrates AI sessions on one machine.