Agent Teams

Agent teams are the level above subagents. Instead of workers that report back to a single caller, you get a team of independent Claude Code sessions that can talk to each other, share a task list, and coordinate on their own.

When to use a team instead of subagents

Use a team when the workers need to debate, challenge each other, or hand work off. Use subagents when the workers just need to go do a thing and bring back an answer.

If you can describe each worker's job in one sentence and never need them to talk, stick with subagents.

Enabling teams

Set the flag in ~/.claude/settings.json.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Check your version.

claude --version

v2.1.32 or later is required.

Two display modes

• In-process. All teammates share your main terminal. Shift+Down cycles between them. Works anywhere. This is the default.
• Split panes. Each teammate gets its own pane. Requires tmux or iTerm2 with the it2 CLI. macOS works best. Windows Terminal and VS Code's integrated terminal are not supported.

Set your preference in settings.

{
  "teammateMode": "tmux"
}

Or pass it per session.

claude --teammate-mode in-process

Starting a team

Just ask. You don't create teams with a flag, you describe what you want and the lead spawns the teammates.

Create an agent team to review PR #142. Spawn three reviewers:
- One on security implications
- One on performance impact
- One on test coverage

Have each review independently and report findings. Synthesize at the end.

The lead session creates a shared task list, spawns three teammates, gives each one a spawn prompt, and coordinates while they work.

Five SF team patterns

1. Parallel PR review

Single-reviewer passes drift toward the reviewer's favourite kind of problem. A team forces breadth.

Create a 3-teammate team to review this branch before merge.

Teammate "security": audit Apex for SOQL injection, sharing model, CRUD/FLS,
and any new Named Credentials. Flag any use of without sharing.

Teammate "perf": audit for SOQL inside loops, DML inside loops, limits on
large collection handling, and governor risk. Prefer evidence from test
output or debug logs.

Teammate "tests": audit Apex and Flow test coverage. Flag any class under
85% or any new class without a *Test.cls.

Report findings as a single markdown document grouped by teammate.

Three focused lenses, one merged report.

2. Multi-layer feature build

Splits the "build this feature" task by layer so no two teammates edit the same file.

Build a Case Deflection feature end to end. Spawn four teammates.

Teammate "apex": force-app/main/default/classes/. Create
CaseDeflectionService, its interface, and tests. No LWC changes.

Teammate "lwc": force-app/main/default/lwc/caseDeflectionPanel/. Wire it to
CaseDeflectionService via @wire. No Apex changes.

Teammate "flows": force-app/main/default/flows/. Create the record-triggered
flow that routes to the deflection service for new high-volume cases.

Teammate "permissions": force-app/main/default/permissionsets/. Add
Case_Deflection permset with the right CRUD/FLS/Apex access. No code edits.

When blocked, message the relevant teammate directly. Do not assume
method signatures; ask apex.

The "do not assume signatures, ask apex" line is important. Teams work because teammates can ask each other instead of guessing.

3. Cross-org comparison

When you need to understand what's different between sandbox, scratch, and production.

Spawn a 3-teammate team. Each connects to a different org.

Teammate "sandbox": org alias `customer-uat`. List every custom object,
field, permset, and flow.

Teammate "scratch": org alias `cs-poc`. Same list.

Teammate "prod": org alias `customer-prod`. Same list, but read-only,
no write tools.

Exchange lists with each other, compute the three-way diff, and produce a
single markdown report showing what exists in which org.

Each teammate connects to a different Salesforce org in its own context. The lead synthesises.

4. Debugging contest

When the root cause is not obvious, one investigator anchors on the first plausible theory. A team stops that.

Users report the Case trigger fails intermittently in production.
Spawn 3 teammates to investigate competing hypotheses.

Teammate "recursion": the issue is a recursive trigger firing from
a flow. Prove or disprove.

Teammate "governor": the issue is a heap or CPU limit under bulk load.
Prove or disprove.

Teammate "sharing": the issue is a sharing recalculation during
high-volume updates. Prove or disprove.

Have them read each other's evidence and update the debate. I want the
surviving theory at the end, with the evidence that kills the others.

The debate structure is what matters. Anchoring disappears when three teammates are actively trying to disprove each other.

5. Customer POC triage

For the week before a go-live when you need everything reviewed at once.

Team of 4 to triage the current POC branch.

"handoff-docs": read docs/ and tell me what's out of date after the last
10 commits. Propose edits.

"test-gaps": run the test suites, report coverage and failures.

"security": audit permsets and named credentials for any customer data
leak risk.

"demo-reset": verify scripts/demo-reset.sh still produces a clean org.
Run it against a fresh scratch.

Report as a pre-handoff checklist.

Four parallel reads of the project. One consolidated list of what to fix.

Hand-rolled coordination: Jag's FDE pod

Jag's SF Skills ships 7 subagents that behave a lot like a team, but they don't use the experimental agent-teams feature on this page. Instead, one of them (fde-strategist) has the Task tool in its allowlist and delegates to the other six. It's a coordinated subagent pattern, not a true team.

Why it matters for this page:

• No experimental flag required. The pod works on stock Claude Code. If you want coordination without opting into experimental team behavior, study the strategist's frontmatter.
• Communication is fan-out only. The strategist talks to each specialist; specialists don't talk to each other. A real team (this page) lets teammates message each other directly.
• Use a true team when specialists need to debate. Use the strategist-plus-subagents pattern when specialists just need to execute narrow, scoped briefs.

The quick heuristic:

Spawning teammates from subagent definitions

If you already have a .claude/agents/apex-reviewer.md subagent, you can reuse it as a teammate.

Spawn a teammate using the apex-reviewer agent type to audit the auth module.

The definition's tools allowlist and model apply to the teammate. The body appends to its system prompt. skills and mcpServers fields in the agent file do not apply to teammates; teammates load those from project and user settings.

Quality gates with hooks

Three hook events are team-specific. Use them to keep teammates honest.

• TeammateIdle. Runs when a teammate is about to go idle. Exit 2 to send feedback and keep them working.
• TaskCreated. Runs when a task is being created. Exit 2 to block creation and send feedback.
• TaskCompleted. Runs when a task is being marked complete. Exit 2 to block and send feedback.

A common SF pattern: block TaskCompleted if tests aren't passing.

{
  "hooks": {
    "TaskCompleted": [
      {
        "command": "sf project deploy validate --source-dir force-app || exit 2"
      }
    ]
  }
}

See Hooks and Custom Commands for the full event list.

Cleaning up

When you're done, tell the lead.

Clean up the team

The lead checks for active teammates, fails if any are still running, then removes the shared team resources. Always have the lead do cleanup. Teammates shouldn't run it because their team context may not resolve correctly.

Team config lives in ~/.claude/teams/{team-name}/config.json. Task list lives in ~/.claude/tasks/{team-name}/. Don't edit either by hand; Claude Code overwrites both on every state update.

Known limitations

• No session resume for in-process teammates. /resume and /rewind do not restore them. You'll need to spawn fresh teammates if you pick up a session.
• One team per lead. Clean up before starting a new one.
• No nested teams. Teammates cannot spawn their own teams.
• Leadership is fixed. The session that creates the team is the lead for its lifetime.
• Teammates occasionally conflict on file edits. Split work by file or folder to avoid overwrites.

When to skip teams

• The task is linear and depends on each step's output. Run a single session.
• You have three narrow, read-only jobs that can report back independently. Use subagents.
• You are already at your token budget. Teams multiply cost by team size.

Teams earn their keep on research, review, and cross-layer feature work. Everywhere else, simpler tools do the job cheaper.

Next

• Subagents for lighter-weight parallelism.
• Hooks and Custom Commands for team-wide quality gates.
• Plugins and Marketplaces for distributing agent definitions to your SE team.