Claude Agent Teams: Setup, Subagents vs Teams, Token Cost, and an X Research Team

Anthropic's docs define an agent team as several Claude Code instances working together: "One session acts as the team lead, coordinating work, assigning tasks, and synthesizing results. Teammates work independently, each in its own context window, and communicate directly with each other." You can also talk to any teammate yourself without going through the lead.

The docs list four components:

Where it lives on disk. Each agent's mailbox is a JSON file at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json, the team config is ~/.claude/teams/{team-name}/config.json, and the task list sits in ~/.claude/tasks/{team-name}/. The team name is session- plus the first eight characters of the session ID. The docs say the config holds runtime state and is overwritten, so do not hand-edit it, and a project file such as .claude/teams/teams.json is not read as configuration.

Tasks and dependencies. A task can depend on others and shows as blocked until they are completed; teammates do not self-claim a blocked task. Claiming uses file locking, so two teammates cannot grab the same task at once, and finishing a task unblocks its dependents automatically.

Context. A teammate loads the same project context as any session (CLAUDE.md, MCP servers, skills) plus the spawn prompt from the lead. The lead's conversation history does not carry over, which is why the docs ask you to put task-specific details in the spawn prompt.

Agent teams are disabled by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your shell or in the env block of a settings.json. Without it, the docs say, no team is set up at session start, no team directories are written, and Claude does not spawn or propose teammates.

Then just ask. There is no team command. You describe the job and the teammates in natural language ("Spawn three teammates to review PR #142: one on security, one on performance, one on test coverage"), and Claude creates the tasks and the teammates. Claude may decide a task is small enough for plain subagents; if so, ask again and say "agent team" explicitly.

Interactive only. "In non-interactive mode with the -p flag, including Agent SDK sessions, Claude doesn't spawn teammates." A named subagent in those runs stays an ordinary subagent. For scheduled or scripted jobs you therefore use subagents, the Agent SDK, or a plain script.

A side effect to know. While the flag is on, a subagent that Claude names launches as a teammate, and Claude names subagents on its own so it can message them later. Teams can therefore form when you did not ask for one. Setting the variable to 0 in user settings.json turns that off for the next spawn without a restart, unless a higher-precedence settings file or managed settings set it to 1.

Display mode. The default teammateMode is in-process: teammates run inside your terminal, you pick one in the agent panel with the arrow keys and press Enter to read or message it, x stops it and Ctrl+T toggles the task list. auto uses split panes when you are already inside tmux or in iTerm2 with the it2 CLI; tmux and iterm2 force a backend. The per-session flag is claude --teammate-mode auto, which the docs call experimental and which is not shown in claude --help.

Which model each teammate gets. First match wins: the model your spawn prompt names, then the model of the subagent definition the teammate was spawned from (inherit means the lead's), then CLAUDE_CODE_SUBAGENT_MODEL, then the lead's model. The old teammateDefaultModel setting was removed in v2.1.234 and is ignored.

Both features give work to helpers with their own context window. The difference is who coordinates and who pays. This table follows the comparison in Anthropic's agent-teams docs:

Pick subagents when a helper only needs to come back with an answer: run the tests, search the codebase, fetch documentation, pull a batch of posts and summarize them. They work in claude -p, they can nest up to three layers below the main conversation, and you define them as Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (user).

Pick an agent team when the helpers need each other: reviewers who should challenge one another's findings, hypotheses that should be argued down, or modules owned by different teammates that must agree on an interface. Anthropic's strongest listed use cases are research and review, new modules, debugging with competing hypotheses and cross-layer changes.

Pick neither for sequential work, edits to the same file, or tasks with many dependencies. The docs say a single session or subagents are more effective there, and two teammates editing one file overwrite each other.

Reuse one definition for both. A subagent definition can be the role of a teammate: "Spawn a teammate using the security-reviewer agent type". For a teammate, Claude Code applies the definition's tools (adding SendMessage and the task tools for in-process teammates), model, disallowedTools and effort; the body is appended to the teammate's system prompt in-process and replaces it in split panes. The definition's skills are not applied, and its mcpServers field only applies to split-pane teammates, so for in-process teammates put MCP servers in project or user settings.

Claude Code bills by token consumption, and a team multiplies the consumers. The agent-teams docs: "Agent teams use significantly more tokens than a single session. Each teammate has its own context window, and token usage scales with the number of active teammates." The cost guide is more specific: token usage is "roughly proportional to team size", and agent teams use "approximately 7x more tokens than standard sessions when teammates run in plan mode".

For a baseline, the same cost guide reports that across enterprise deployments the average Claude Code cost is around $13 per developer per active day and $150 to $250 per developer per month, with 90% of users below $30 per active day. A team of four on long tasks sits on the expensive side of that range, because each member re-reads its own growing context on every turn.

Anthropic's own cost advice for teams: use Sonnet for teammates, keep teams small, keep spawn prompts focused (everything in them is in the teammate's context from the start), and shut teammates down when their work is done, because "each active teammate continues consuming tokens until it exits or the session ends".

Cache detail worth knowing. An in-process teammate's requests are outside the main conversation's cache bucket, so its prompt cache holds for five minutes by default, also on a subscription. Setting subagentPromptCacheTtl to 1h keeps it longer, and the API bills one-hour cache writes at a higher rate. A teammate that sits idle for more than five minutes and then gets a message re-reads its context at full input price.

How it lands on a plan. On Pro, Max or Ultra the tokens count against your plan's usage windows; on the API or a cloud provider they are billed per token. /usage breaks recent usage down by subagents and other sources. Plan names and prices are on our Claude Code pricing page, so we do not repeat them here.

Team size. There is no hard cap on teammates. The docs recommend starting with 3 to 5, about 5 to 6 tasks per teammate, and note that three focused teammates often beat five scattered ones.

The feature is marked experimental and the docs list these limitations. They decide whether a team fits a long or unattended job:

No resume for in-process teammates. /resume and /rewind do not restore them; after a resume the lead may message teammates that no longer exist, and you have to ask it to spawn new ones.

Task status can lag. Teammates sometimes fail to mark tasks completed, which blocks dependents. Check the work and update the task, or ask the lead to nudge the teammate.

Shutdown is not instant. A teammate finishes its current request or tool call first, and it can reject a shutdown request with an explanation.

One team per session, no nesting, fixed lead. A session has exactly one team; teammates cannot spawn teammates; you cannot promote a teammate to lead.

No background subagents from in-process teammates. A teammate's own subagents run in the foreground, and a definition with background: true errors.

Permissions start from the lead. Teammates inherit the lead's permission mode at spawn (including the mode that skips every permission check), you cannot set a different mode per teammate at spawn time, and their permission prompts appear in the lead session. Pre-approve the tools a team needs before you start it.

Split panes need tmux or iTerm2. They are not supported in the VS Code integrated terminal, Windows Terminal or Ghostty; in-process mode works everywhere.

Quality gates. Three hooks exist for teams: TeammateIdle (exit code 2 keeps a teammate working with feedback), TaskCreated and TaskCompleted (exit code 2 blocks the action and sends feedback).

Anthropic suggests starting with research tasks that have clear boundaries and do not write code. Researching a topic on X fits: one teammate collects posts, one tags them, one writes the memo, and each hands off through the task list. The only shared resource is the X data, which comes from the TwitterAPI.io MCP server.

The data server. We sent initialize to mcp.twitterapi.io/mcp while writing this page: it answered as twitterapi-mcp 0.1.0 with 12 read tools (search_tweets, get_user_info, get_user_last_tweets, get_user_mentions, get_tweet_replies, get_trends and others), and its instructions say to paste the API key as the Bearer token. Reading X data this way needs no X account.

Why project scope. In-process teammates load MCP servers from project and user settings and ignore a definition's mcpServers field, so add the server with --scope project (it lands in .mcp.json) or at user scope. The definitions then allow the whole server with mcp__twitterapi__* in tools.

Permissions first. Because teammate prompts surface in the lead and a teammate starts with the lead's mode, the settings file pre-approves the MCP tools and writes under reports/. Nothing else needs approval for a read-only research job.

The spawn prompt. It names each teammate, points it at its definition, sets page budgets and makes the tasks depend on each other so the classifier waits for the collector. We also tell every teammate to shut down when done, one of the cost habits Anthropic's guide lists:

Create an agent team to research how developers on X talk about "agent teams". Spawn three teammates from our agent definitions and name them exactly: - collector, using the x-collector agent type: query "agent teams" claude -filter:retweets, Latest, at most 20 pages. Then the same for: claude subagents -filter:retweets, 15 pages. - classifier, using the x-classifier agent type: starts when collector's task is completed. - writer, using the x-writer agent type: starts when classifier's task is completed. Make classifier's task depend on collector's, and writer's on classifier's. Use Sonnet for every teammate. Ask each teammate to shut down when its task is done.

What a run does. The collector calls search_tweets page by page and saves JSON; the classifier reads the files and writes aggregates only; the writer turns them into a memo. The plain Python script further down does the collector's and classifier's work in one process, which is the right choice when you want this on a schedule, since claude -p will not spawn teammates.

We searched X for posts that contain the phrase "agent teams" and the word claude, newest first and top-ranked, and for posts with claude and subagents, newest first. After removing duplicates the agent-teams pool held 415 posts from 341 accounts; 67.7% were in English.

Subagents are the bigger conversation. Posts naming Claude and subagents arrived at 178.8 a day against 2.1 a day for agent teams, about 85.1x. The subagents query is looser (two words anywhere, not a phrase), so read the ratio as direction, not precision. It matches the docs' framing: subagents are the everyday tool, teams the experimental one.

Attention is concentrated. The median agent-teams post in the Latest sample got 7 likes and 769 views; the top 10% passed 186 likes and 32,267 views. In the Top sample the median was 222 likes and 35,654 views, and 74.9% of those posts carried an image or video. About 90.4% of the Latest sample fell in the final five weeks of its window, so the topic was picking up when we collected; search coverage of older posts can be thinner, so treat that as indicative.

What people talk about. Of the 281 English posts, 38.4% mention cost, tokens or usage limits, 38.1% review, debugging or tests, 33.8% parallel work or orchestration, 29.9% also mention subagents, and 29.9% talk about setup or the experimental flag (the exact variable name appears in 6.3% of all agent-teams posts). MCP comes up in 17.1%, Opus in 16.0%, and tmux or split panes in only 3.9%. These are keyword matches, so they are upper bounds.

The official accounts. In the last 100 posts of @claudeai (184.0 days) and 100 of @AnthropicAI (174.2 days), none used the words agent teams or subagents; @claudeai named Claude Code in 19 posts. The feature is documented on code.claude.com rather than announced on the main accounts.

Model tokens are one bill; the X data is the other, and it is predictable because it is priced per post returned. Tweet endpoints such as /twitter/tweet/advanced_search and /twitter/user/last_tweets cost 15 credits per tweet returned, which is $0.15 per 1,000 tweets; a full 20-post page is $0.003, and a request that finds nothing is billed the 15-credit minimum, $0.00015. The MCP tools call the same API, so the same rates apply.

The ratio. $5 against $0.15 per 1,000 posts is about 33x. For our 952 posts that is $4.76 on X's pay-per-usage rate card (docs.x.com/x-api/getting-started/pricing, which also caps pay-per-usage at 3M post reads a month) against $0.14 with us. Profiles cost $0.18 per 1,000 with us and $0.010 per user read on X.

What dominates. This study's posts came to $0.14; Anthropic's cost guide puts the average enterprise Claude Code day at around $13 per developer, so on a research team the model tokens are the line to watch, not the X data. The cost levers are the ones Anthropic lists (Sonnet, small team, short spawn prompts, shut down when done) plus one of ours: let the collector save raw pages to disk and pass file paths, not post text, to the other teammates, so the posts are paid for once and not re-read into three contexts.

Getting a key. New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days); that covers this study several times over. Requests run at 0.2 per second before the first payment and 20 per second once paid, which matters if several teammates call the server at once. Purchased credits never expire; plans and rate limits are on the pricing page.

Question. How do people on X talk about Claude Code agent teams, how loud is the topic next to subagents, and what does the X data for such research cost?

Queries and accounts. /twitter/tweet/advanced_search with "agent teams" claude -filter:retweets (Latest and Top) and claude subagents -filter:retweets (Latest), plus /twitter/user/last_tweets for the organization accounts @claudeai and @AnthropicAI.

Window and sample. The most recent posts available for each query at collection time, collected in 2026: 952 posts in 51 requests, 415 unique agent-teams posts after deduplication. Topic tags come from fixed keyword lists in the study's analyze.py.

What the sample cannot show. Search results are a sample, not a census, and the two queries are worded differently, so the subagents ratio is indicative. Keyword tags overcount broad words such as "test" and "usage". The study says nothing about how well agent teams work, only how people talk about them, and we did not run the team's token bill against a fixed benchmark.

Privacy. Aggregates only. Search results come from private individuals, so their raw pages stayed out of the repository; the study folder keeps de-identified rows with no ids, handles, text or links. Only organization accounts are named.