Claude Code Agent Teams: Multi-Session Guide (2026)
Research preview - disabled by default, behavior may change. Claude Code agent teams are multiple sessions running in parallel: one "lead" agent coordinates, one or more "teammates" execute, and the whole team shares a task list plus direct messaging - very different from a subagent (runs inside the calling session's context, no persistent window of its own, no back-and-forth messaging). This guide covers: how to enable it, how it differs from subagents/skills/workflows, what cross-session messaging actually is, the real limitations, and an honest read on AgentKit.
- This is a research-preview feature, and the enable mechanics already changed once (before/after v2.1.178 - the manual team-create tools no longer exist). Details here were cross-checked against the official docs at time of writing (08/2026) - verify the live docs before you depend on them.
What agent teams actually are
Agent teams is a Claude Code research-preview feature that lets multiple sessions run in parallel inside one "team": a lead agent coordinates, and one or more teammates execute tasks. Each teammate gets its own context window - it doesn't share context with the lead or with other teammates - and the whole team shares one task list plus a direct-messaging channel (mailbox). Per the official docs at code.claude.com/docs/en/agent-teams (checked 08/2026), this is a coordination layer sitting on top of independent Claude Code sessions - not a new model, not a separate API.
One line to avoid confusion: agent teams are not AgentKit's "advisor" or "kongming" personas - those work very differently (see the honest read at the end).
Agent teams vs subagents
If you're already comfortable with Claude Code subagents, here's the direct comparison from the docs (condensed):
| Criteria | Subagents | Agent teams |
|---|---|---|
| Context | Runs inside the calling session's context, no persistent window of its own | Each teammate has its own context window |
| Communication | Takes a task, returns a result - no back-and-forth messaging | Messages directly through a mailbox while running |
| Coordination | The main session decides which subagent to call and when | Lead + shared task list; teammates self-claim or get assigned work |
| Best for | Specialized, repeatable work needing context isolation (code review, tests...) | Parallel exploration, multiple perspectives on one problem at once |
| Token cost | Lower - one context, called on demand | Noticeably higher - every teammate is a full session running in parallel |
Short version: a subagent is "delegate the work, get a result back"; agent teams is "a group working together and messaging each other directly." To scale subagent orchestration up further, see orchestrating subagents at scale.
Who holds the plan: subagents vs skills vs agent teams vs workflows
This is the core info-gain of the article - a 4-way comparison pulled directly from the Claude Code docs (code.claude.com/docs/en/workflows, checked 08/2026) that none of the competitors we checked, EN or VI, reproduce in full:
| Subagents | Skills | Agent teams | Workflows | |
|---|---|---|---|---|
| What it is | A child agent, called on demand, own context for one task | Instructions loaded by context (progressive disclosure) | Multiple parallel sessions, lead + teammates, shared task list | A script (Claude writes it) fanning out subagents in the background |
| Who decides what runs next | The main session decides | The main session, guided by the skill's instructions | Lead + each teammate decide within their assigned scope | Logic inside the script decides, not Claude turn-by-turn |
| Where intermediate results live | Returned into the calling session's context | No separate state - it's just instructions | The shared task list + mailbox | Inside the workflow's own runtime, separate from the main context |
| What's repeatable | Yes, if you redefine the agent | Yes - that's the point of a skill | Not automatically - each team is one interactive session | Yes - saved as a reusable command |
| Scale | One agent at a time, sequential or a few parallel | Not agent-bound - it's instructions | Bounded by how many sessions you actually open in parallel | Up to hundreds/thousands of subagents in one run |
| Interruption | Follows the main session | Not applicable | No resume yet for in-process teammates (see limitations) | Can pause/resume via /workflows |
None of the competitor articles we checked reproduce this exact 4-way framing - most only compare agent teams to subagents and skip skills and workflows entirely. For a full deep dive on workflows/ultracode, see Claude Code Dynamic Workflows.
Enabling agent teams - CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
Agent teams are disabled by default. Turn them on with an environment variable in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "true"
}
}A few things worth remembering (per the docs, checked 08/2026 - verify against the Claude Code version you're actually running before relying on this):
- Only works in an interactive session - it does not run through
-por the Agent SDK. - As of the current setup (post-v2.1.178), you don't need to manually call
TeamCreate/TeamDeletetools the way some older write-ups describe - those tools no longer exist in the current flow. If you read a guide describing a manual team-create step, it was likely written before this change - a concrete example of the "may change" warning Anthropic itself gives.
Starting your first team and the shared task list
Once enabled, open with a task large enough to split across perspectives, for example:
Spawn a team of 3 teammates to review this PR:
one for security, one for performance, one for test coverage.
Report findings back to me.Claude Code creates a shared task list for the whole team, with familiar states: pending, in progress, completed. A few mechanics worth knowing:
- Dependency blocking - a task can wait on another task finishing before it starts.
- Self-claim or lead-assigned - a teammate can claim a pending task itself, or the lead can assign it directly.
- File-locking on claim - when a teammate claims a task touching a specific file, a lock keeps two teammates from editing the same spot at once.
Cross-session messaging - a different feature, not a team
This is where most competitors (EN and VI) blur the line, treating it as "team messaging." The docs actually treat it as a separate feature: cross-session messaging lets two independent Claude Code sessions - even on another machine, or via Remote Control - pass messages via ListAgents/SendMessage (or the /list-agents command), without both belonging to the same Claude-supervised team.
When to use which: if you want Claude itself to coordinate a group through one shared task list, use agent teams. If you have a few independent sessions you're steering yourself and just need them to pass messages on request, cross-session messaging is the right, lighter-weight tool - you don't need to turn on the full team mechanism for it.
Platform note: cross-session messaging currently only runs on macOS/Linux - there's no native Windows support yet. WSL2 counts as Linux, so it still works there. The team's split-pane display mode also needs
tmuxor iTerm2, and explicitly does not work in Windows Terminal. We haven't seen a single competitor (EN or VI) mention this - worth flagging given how many dev machines among this site's readers run Windows.
Agent view - the dashboard for parallel background sessions
A related, easily-confused feature: agent view, opened with claude agents. It's a dashboard listing your parallel background sessions - unlike agent teams, there's no messaging between sessions, it's purely a monitoring screen. It's also research preview.
Worth correcting a fairly common mix-up: isolation via a dedicated git worktree per session is agent view's mechanism (for background sessions), not a default behavior of agent teams. Some write-ups describe agent teams as auto-spawning a separate worktree per teammate, framed as a kind of "parallel universe" - the agent teams Architecture docs describe no such mechanism; they only describe lead/teammate/task list/mailbox, with no mention of automatic worktrees.
A realistic use case: parallel PR review
The strongest use case in the official docs (and the one I'd actually reach for) is a parallel PR review: spawn 3 teammates, each reading the same PR through a different lens - security, performance, test coverage - then reporting back to you. Because each teammate has its own context, they don't step on each other reading the same diff.
Honestly: this walkthrough is modeled on Anthropic's own documented use case, not a first-hand run with specific numbers (issue counts, PR counts). If you see another review citing precise figures like "X issues found in Y minutes," it's worth asking whether they actually ran it or are just paraphrasing the docs. Another pattern worth trying: give a hard bug to multiple teammates working competing hypotheses, then have the lead synthesize which hypothesis best fits the evidence.
Either pattern only pays off when the sub-tasks genuinely benefit from separate context - reading the same diff through different lenses, or chasing different root-cause theories without one teammate's assumptions polluting another's. For work that's mostly sequential (implement, then test, then document) a plain subagent chain is usually cheaper and easier to reason about than standing up a whole team.
Limitations - what doesn't work yet
Because this is a research preview, the docs list their own current limitations plainly - worth reading before you bet an important workflow on this feature:
- No resume for in-process teammates after closing your terminal - closing the session loses that teammate.
- Task status lags - the task list doesn't always reflect what a teammate is doing in real time.
- One team per session - you can't run multiple teams in parallel under one lead session.
- No nested teams - a teammate can't spawn its own sub-team.
- Split-panes need tmux/iTerm2, and don't work in Windows Terminal (same caveat as cross-session messaging).
This is also why the article keeps stressing "research preview": the enable mechanics already changed once (dropping the manual team-create-tool step), so this limitations list is a reasonable candidate to change too. Don't lock a production-critical workflow to the exact details/behavior described here without re-checking.
Honest AgentKit angle: can its personas be teammates?
The direct question: can AgentKit's advisor and kongming act as teammates in an agent team? No, not as a persistent teammate.
kongmingis one-shot: one prompt in, one answer out, no back-and-forth turns.advisoris interview-relay: it asks questions one at a time and returns to the main session between them - not an independent session running in parallel, messaging through a mailbox.
Neither is built for the persistent, multi-turn messaging a teammate needs (per docs.agentkit.best/en/beta/concepts/advisory-supervision, checked 08/2026).
But there's a real, worth-stating-plainly nuance instead of glossing over it: Claude Code lets you spawn a teammate using any agent type defined at the project/user/plugin level - and AgentKit's runtime adapter installs the kit's agents as native Claude Code subagent definitions. So technically, a task-execution agent from an AgentKit kit (not advisor/kongming) can be named as a teammate. That's not the same as "AgentKit ships ready-made teams" - state the boundary plainly: AgentKit is a paid kit that gives you personas/skills to delegate work to; agent teams is Claude Code's free coordination mechanism you plug them into yourself - not a packaged "team" product from AgentKit. See the full AgentKit review for more.
Want a solid set of prebuilt personas/skills to hand off to a teammate? AgentKit packages skills and subagents for Claude Code (and Codex) - usable as task-agents inside a team you build yourself, not a packaged "team" product. One-time paid, no recurring fee listed on the page.
Frequently asked questions (FAQ)
What does CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS do?
It's an environment variable (set in settings.json) that enables Claude Code's agent teams feature, disabled by default since it's still a research preview. It only works in an interactive session, not through -p or the Agent SDK.
How is agent teams different from subagents?
A subagent runs inside the calling session's context, takes a task and returns a result, with no back-and-forth messaging. Agent teams involve multiple independent sessions (each teammate with its own context), sharing a task list and messaging directly through a mailbox while running - noticeably higher token cost.
Does cross-session messaging work on Windows?
Not natively yet - it currently only runs on macOS/Linux. WSL2 counts as Linux, so it still works there. The team's split-pane display mode also needs tmux or iTerm2, and doesn't work in Windows Terminal.
What's the token cost of a team compared to a single session?
Noticeably higher, because every teammate is a full session running in parallel with no shared context with the main session. The docs don't give a fixed figure - only reach for this when you genuinely need parallel perspectives, not when one agent working sequentially would do.
Can I resume a team after closing my terminal?
Not yet. Per the current limitations, in-process teammates can't resume after you close the session - closing the terminal loses that teammate. This is one of the limitations the docs list plainly themselves.
Is this feature stable enough for daily work?
Not really - it's still a research preview, and the enable mechanics already changed once (dropping the manual team-create-tool step). Fine to try on non-critical parallel exploration; not yet something to build a required daily workflow around given how much stability it still needs.
Conclusion
Agent teams is still a research preview - strong for parallel exploration (multiple perspectives on one problem at once), not a replacement for simpler sequential work that a subagent or skill already handles. Keep the 4-way "who holds the plan" table as your decision shortcut: a single agent following sequential instructions - subagent/skill; long, collaborative sessions that message each other - agent teams; work bigger than one context window or needing hundreds of subagents - workflow. Try it on something non-critical first, read the limitations closely, and don't lock a production process to details that can change at any time.