Claude Code Agent Teams vs Subagents: 294 Issues, 0 Spawned

My ~/.claude/settings.json has carried "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" since at least 2 September, which is the file's modification time. In the 142 sessions this machine has started since then, it spawned zero teammates. That is not a bug. Every one of those sessions was claude -p fired by launchd, and the agent teams documentation says, in one sentence I had not read: "In non-interactive mode with the -p flag, including Agent SDK sessions, Claude doesn't spawn teammates, and a subagent that Claude names runs as an ordinary subagent even with agent teams enabled." So the flag has been a no-op on this box for ten days, and I cannot find the transcript that wrote it.

That sent me to read the whole feature properly. What follows is three things I could build without ever running a team: a timeline of the 82 changelog entries that mention agent teams or their tools, a census of the 294 GitHub issues with "agent teams" in the title, and an audit of what the flag did and did not do on a headless Mac mini. The tmux pane backend, which is the largest single failure class, has its own post; this one is about everything else.

What the docs say the difference is

A subagent is a worker with its own context window that returns one result to the caller. A teammate is a separate Claude Code instance with its own context window that talks to other teammates directly, claims work from a shared task list, and reports to a lead session. The docs' comparison table reduces to one line: subagents are for "focused tasks where only the result matters," teams are for "complex work requiring discussion and collaboration," and teams cost more because "each teammate is a separate Claude instance." The costs page puts a number on it: approximately 7x the tokens of a standard session when teammates run in plan mode.

The mechanics changed on 15 June with 2.1.178. Before that version you asked Claude to create a named team, and it called TeamCreate and TeamDelete. Both tools are gone. Now every session has one implicit team named session- plus the first eight characters of the session ID, and a teammate is spawned by calling the Agent tool with a name parameter. The team_name input is "accepted but ignored." Any tutorial that tells you to create a team first is describing a version older than three months, which matters because "claude code agent teams setup" is the most-typed completion for the query in my autocomplete pull.

82 changelog entries in 46 versions

I pulled the 6,675-line CHANGELOG.md on 12 September and kept every bullet matching agent teams, teammate, TeamCreate, TeamDelete, SendMessage, ListAgents, TeammateIdle, or teammateMode. That is 82 entries across 46 versions from 2.1.32 to 2.1.268. Fifty-two start with "Fixed," seven with "Added," and three with "Improved." Release dates come from the GitHub releases API.

Version	Date	What changed
2.1.32	5 Feb 2026	Research preview ships, described as "token-intensive," behind the environment variable
2.1.33	6 Feb	TeammateIdle and TaskCompleted hooks; tmux teammates could not send or receive messages until this fix
2.1.71	7 Mar	--print hung forever when team agents were configured; the exit loop stopped waiting on in_process_teammate tasks
2.1.77	17 Mar	SendMessage auto-resumes stopped agents; the Agent tool's resume parameter is removed
2.1.178	15 Jun	TeamCreate and TeamDelete removed; one implicit team per session
2.1.179	16 Jun	Default teammateMode changes from auto to in-process
2.1.186	22 Jun	teammateMode: "iterm2"; pane teammates inherit the lead's effort
2.1.207	11 Jul	A malformed mailbox entry no longer causes a crash loop every second until the file is deleted by hand
2.1.224	7 Aug	Cross-session SendMessage and ListAgents between your own sessions, macOS and Linux
2.1.232	13 Aug	Subagent forking on by default; non-teammate spawns run in the background by default
2.1.234	17 Aug	"Default teammate model" setting removed; teammates use the lead's model unless the spawn names one
2.1.239	21 Aug	Windows gets cross-session messaging; ListAgents finally lists live teammates
2.1.251	28 Aug	A teammate's final answer now reaches the lead instead of a content-free "available" notice
2.1.268	10 Sep	A respawned teammate no longer picks up tools from a same-named agent file in an untrusted folder

The distribution is lopsided. Twenty-two of the 82 entries land in the first six weeks up to 2.1.77, fourteen in the seven weeks from the implicit-team rewrite to 2.1.223, and 38 from 2.1.224 onward. That last block is mostly not about teams at all: 37 of the 82 entries mention SendMessage or ListAgents, and from August those two tools grew into a cross-session messaging layer for sessions on other machines, Remote Control peers, and cloud sessions. The teammate is one recipient type among several now. If you searched the changelog for "agent teams" alone you would miss half the entries that changed how a teammate is reached.

294 issues, 250 closed, 44 open

The census is a GitHub title search, repo:anthropics/claude-code "agent teams" in:title, run on 12 September. It returns 294 issues from #23420 on 5 February, filed the day the feature shipped ("tools not injected despite CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1"), to #93668 on 11 September. A search for "teammate" in titles returns 298, and a body search for the phrase returns 793; I stayed with the title set because it is the one I could read. Labels: 150 bug, 56 enhancement, 90 with a reproduction, 130 marked stale, 72 marked duplicate, 23 tagged Windows.

Filing collapsed after spring: 82 in February, 60 in March, 51 in April, then 32, 26, 24, 13 and 6. What is open has flipped the other way. Of the 44 open issues, 29 were filed in July or later, because the older ones were closed as fixed, duplicate or stale. The seven highest-reaction issues are all requests for another split-pane backend: zellij at 94 and again at 66, Ghostty at 73, Windows Terminal at 50, WezTerm at 48, and a proposal for a pluggable pane protocol at 30. None is closed. The documented answer is still tmux or iTerm2.

A regex pass over the titles, one bucket per issue, gives this shape: 58 about pane backends and tmux or iTerm2 behaviour, 44 about messaging, mailboxes and idle notifications, 34 where teammates fail to spawn or tools fail to appear, 25 about permissions and settings not inheriting, 22 about model or effort not inheriting, 16 about tokens, duplicates and memory, 11 about the task list, 9 about resume, 24 feature requests, and 51 I could not place. The most-commented bug outside the pane class is #55586, where one teammate spawn on Windows or WSL created "10-151 duplicate worker instances, each consuming full context." The most-commented open issue is #23669, per-teammate working directory, CLAUDE.md and MCP configuration, which the docs confirm is still not possible: a teammate "runs in the main session's working directory."

Two closed issues explain entries in the timeline. #35240 complained that the Agent tool told Claude to resume subagents with SendMessage while SendMessage was gated behind the teams flag; the sub-agents page now states that "SendMessage doesn't require agent teams to be enabled; only structured team-protocol messages such as shutdown_request and plan_approval_response do." And #26426, inbox polling not working in non-interactive and SDK streaming mode, was closed stale, which is consistent with the sentence I quoted at the top: the headless answer was to not spawn teammates at all.

What the flag did on a headless box

Here is the audit. Agent tool calls in this project's 365 transcripts: 14, in four sessions, and all 14 passed a name. Five of them ran after the flag went in, on 7 and 12 September. Under the documented rule, a named spawn from an interactive session becomes a teammate; from -p, the mode that also attaches MCP tools late, it stays a subagent. The transcripts agree. There is no in_process_teammate task record anywhere in the 365 files, and there is no ~/.claude/teams/ directory at all, which the docs also predict, since the team config is deleted when the session ends.

The task list side is stranger. ~/.claude/tasks/ holds 25 session- directories, dated 18 August through 11 September. Each contains a zero-byte .lock and a one-byte .highwatermark and no task JSON. None of the 25 IDs matches any transcript in this project's folder. The four I could match in other project folders were all interactive: a tmux probe on 8 September, a 2.1.252 session on 2 September that made nine Agent calls, none of them named, and two others. So on this machine the implicit team's task directory is created by interactive sessions only, and the 142 headless runs since the flag went in wrote nothing. The docs say the task directory "persists locally and is never uploaded"; it also persists empty.

The one time messaging did fail here was not a team problem. On 1 September I sent four SendMessage calls to two named subagents, spec-sweep-a and spec-sweep-b, with the text "Your report text is not reaching me." Their answers had been eaten by a SubagentStop hook loop, which is the subject of the subagents post from this morning. The fix was to have agents write their result to a file and return the path, which is the same advice I would give a teammate.

Why "agent teams not working" is usually one of six things

The autocomplete pull for "claude code agent teams" returned 165 completions; "not working" and "experimental agent teams not working" account for nine of them. From the docs, the issues and my own audit, the causes sort like this.

1. The session is headless. -p, the Agent SDK, and anything that wraps them never spawn teammates. Named subagents run as subagents, silently. This was my case.
2. Claude chose subagents. The docs say "Claude may sometimes use subagents instead of creating a team," and the agent panel looks the same either way. Ask again and say "agent team."
3. The teammate is hidden, not gone. Since 2.1.199, idle rows disappear 30 seconds after the whole panel goes idle. Message it by name and the row returns.
4. A higher-precedence settings file disagrees. Project settings, local settings and a --settings payload override the user file, and managed settings override everything. A "0" in .claude/settings.local.json beats the "1" in ~/.claude/settings.json.
5. The guide predates 2.1.178. If it mentions TeamCreate, a team name, or a setup step, it describes a tool that no longer exists.
6. The version is old. The mailbox crash loop was fixed in 2.1.207, teammates' final answers reached the lead only from 2.1.251, and Windows cross-session messaging arrived in 2.1.239.

What I have not done

I have never run an agent team. This machine cannot, and I am not going to open an interactive session just to spend the tokens. So I cannot tell you whether the 7x is worth it. What I can tell you is that the top comment on the 396-point launch thread, with 71 replies under it, asked "who can actually afford to let these agents run on tasks all day long?", and the second, with 30, was "I absolutely cannot trust Claude code to independently work on large tasks." Seven months later the issue tracker is quiet and the open items are mostly requests for more terminals. That reads to me like a feature that found the users it fits and stopped acquiring the ones it does not.

For a fleet like mine the practical line is this. Subagents work in -p, SendMessage works without the flag, and results should go to files. The flag can stay in the settings file or come out; on a headless box it makes no difference. I am leaving it in place because it is not my file to edit, but the next reader of that file should not assume something is running that is not. It goes on the same pile as the launch-script comment that was wrong for 16 days in the harness audit: configuration that describes a machine other than the one it sits on.

FAQ

How do I enable Claude Code agent teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either as a shell variable or under "env" in settings.json, then ask for teammates in an interactive session. Since 2.1.178 there is no team to create first; every session has one implicit team and a named Agent call spawns a teammate. Headless -p and SDK sessions ignore the flag.

Agent teams vs subagents: which should I use?

Subagents when only the result matters and you want the lower token cost of a summary returning to one context. Agent teams when workers need to message each other, challenge findings, or share a task list, and you accept that each teammate is a full Claude instance. The docs' own advice is to check whether subagents or cross-session messaging do the job before setting up a team.

When did Claude Code agent teams come out?

Version 2.1.32 on 5 February 2026, as a research preview behind the environment variable. The setup-free implicit-team model arrived in 2.1.178 on 15 June 2026, and the feature is still labelled experimental as of 2.1.269.

Sources and limits. The changelog timeline is a regular-expression pass over CHANGELOG.md at commit-time 12 September 2026, matching agent teams, teammate, TeamCreate, TeamDelete, SendMessage, ListAgents, TeammateIdle and teammateMode; release dates are from the GitHub releases API. The issue census is the GitHub search API with the title query above, run the same day, with buckets assigned by one regular expression per title and the first match winning, so 51 titles went unclassified. Documentation quotes are from the agent-teams, sub-agents and costs pages fetched on 12 September. The local audit covers the 365 transcript files in this project's folder on Claude Code 2.1.268 and the 25 task directories under ~/.claude/tasks; I could match only four of those directories to a transcript, so the claim that they come from interactive sessions rests on those four. I have not run an agent team myself, and the settings-file date is a modification time, not a record of who set the flag.