Reading a 30-page API changelog and drafting a migration FAQ runs about three hours by hand.
Claude Code writes a first draft in roughly 40 seconds, but you then spend 25 minutes checking links and numbers.
The real time sink is deciding which changes break users, not the typing.
That decision is what Agent Teams is built for. One session becomes the lead, and three to five independent Claude Code instances take separate angles: policy, evidence, migration steps, writing. They message each other mid-run instead of you relaying text between tabs.
By the end of this article you will know whether your task needs a team at all, and if it does, the exact flag, the starter team size, and the brief to paste.
You will also know what the token bill looks like before you run it.
| Option | Token cost | Communication | Best for |
|---|---|---|---|
| Subagents | Lower — helpers share one session | Report only to the main agent | Single-pass work: summarize, extract, draft one answer |
| Agent Teams | Higher — each teammate is a full separate Claude Code instance | Teammates message each other directly through a lead | Work that needs discussion, challenge, or synthesis across angles |
What Claude Agent Teams Actually Adds
One Claude Code session becomes the team lead. It coordinates the work, assigns tasks, and turns the results into the single answer you read at the end.
Set the feature up and you are not opening more chat windows. You are appointing one instance to run four others.
The teammates are not chat panes either. Each is a full Claude Code instance with its own context window.
That's the working memory a single instance carries in a conversation, and each teammate gets its own. They message each other directly, so you never copy text between tabs.
The test case: the lead hands the same 30-page public API changelog to four instances, split as policy, evidence, migration steps, and writing. Mid-run, the evidence instance messages the writing instance that a claim changed, before either leaves it wrong.
The catch sits in that one-sitting design. There is one team per session and no nested teams. The lead is fixed for the session's life, and in-process teammates cannot be resumed later. Plan the whole run before you start it.
The setup now fits in one sentence: one lead, 3 to 5 independent teammates, task status read through the lead. If you can say that and name what each teammate checks, this is the setup.
What a team run costs
Prices as of November 2026; confirm on Claude's pricing page.
Use a Team Only for Discussable Work
Subagents are the cheaper option when the parts of the job do not need to talk. They are helpers inside your one session: each takes a slice, reports back to the main assistant, and stops there.
None of them reads another's work, and that is exactly why a run of them costs fewer tokens than a team.
A team exists for results that have to disagree before they agree. Each extra member is a separate paid instance, so the bill climbs with every one you add. You pay that premium for argument, and only for argument.
For a single answer, or anything one assistant finishes in one pass, stay with one session or subagents. A team piles coordination on top of a job that never needed it.
Take the same changelog. Summarizing all 30 pages in a single pass is a subagent job. Deciding which changes break users, which sources hold up, and how to word the FAQ is four jobs that have to talk to each other.
So the rule you apply before any setup: choose a team only when at least two teammates would need to compare or challenge each other's findings. If you cannot name those two, you do not need a team.
⚠️ COMMON MISTAKE
Do not open with eight teammates
Anthropic's docs recommend starting with 3 to 5 teammates and 5 to 6 tasks per teammate. A larger team doubles the number of full instances in the run, and each one carries its own context window. Watch actual usage on a small team before scaling.
Turning the Team Switch On First
Agent Teams ships switched off and labeled experimental, so you will not see anything team-shaped no matter what you type until you flip it.
The switch is given as CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, set to the value 1. Set it in settings.json, or in the environment. Set it to true and it will not take.
Then make a request that needs more than one worker. A working flag changes the shape of the reply. You get a lead opening separate instances, giving each one tasks, and reporting back through itself, not one session answering alone.
Before adding more moving parts, it helps to know which add-ons are worth installing for the job.
Before you rely on it: experimental means behavior and flags can move between releases. Check Claude Code's current docs for where settings.json lives and which version you need first. Otherwise a small update can leave you staring at a flag that quietly does nothing.
Team jargon, decoded
Start with 3 to 5 Teammates
A team that answers also bills, and the first billable choice is how many instances the run holds.
Anthropic's guidance in its docs opens at three to five teammates, each carrying five or six tasks. Six instances at once is not where a first run starts.
Every teammate is a full instance holding its own context, so the bill climbs with each one you add. Context means the working memory that instance keeps, including the changelog and every message it has read. That spending is measured in tokens.
Token is the unit a model bills by: roughly a word fragment of text sent or received. Doubling your teammates from four to eight doubles the instances, and doubles that spend. You get four more memories, never a cheaper rate per memory.
One team per session, with no nested teams, means the headcount you pick is the whole run. There is no sub-lead to slot in where a teammate would go. Four teammates, five tasks each, one lead, one session: twenty tasks, all tracked through the lead.
🧭 The setup, in order
Set the flag
Add CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to settings.json or the environment.
Open a clean project
Start Claude Code in the folder holding the public document and nothing private.
Paste the lead brief
Type the four-teammate brief so the lead knows the goal, team size, and output table.
Watch the run
Read the in-process rows through the lead, expecting idle rows to collapse after 30 seconds.
Check usage
Before adding a fifth teammate, review the token usage the four-teammate run consumed.
Write the Lead's Brief and Task Split
The number of teammates decides how many instances run. The brief decides what each one does and what shape the answer arrives in.
No brief can add a layer of command either. One lead holds the session's whole life, and nesting is off, so four teammates is the full structure.
Name the lead's duties in the text itself. It coordinates the work, hands each teammate its five tasks, flags claims with no source behind them, and folds everything into a single answer. Then state one messaging rule, shared by all four.
Paste this into the lead session, with the changelog attached. The lead splits policy, evidence, migration steps and writing into four instances, five tasks apiece, and every teammate messages another only when a finding changes that teammate's work.
Everyone returns the same columns, so nothing needs stitching later.
Watch the Run Without Losing the Thread
The run looks like a single terminal view, not a dashboard, and a quiet panel is normal. The default display is in-process. Split panes need tmux or iTerm2 with the it2 CLI installed first.
What you will actually see: idle teammate rows hide after 30 seconds, and when more than three sit idle the extra rows fold into one line.
A five-teammate run with all five idle shows three rows plus a line reading "2 idle agents." The panel looks emptier than the team is.
Task status can lag too, and in-process teammates cannot be resumed after a session ends. Treat the run as one sitting. Read the shared task list instead of trusting every row for what is finished.
Quick check: if a row vanishes, it went idle, not away. The synthesis the lead hands back is the source of truth. The rows are only a progress display, and a stale one still ends in the same table.
Subagent or Agent Team
Choose subagents
- One assistant finishes the job in a single pass
- You need a summary, extraction, or one draft
- Token budget is tight and you want lower cost
- Helper agents only need to report to the main agent
Choose Agent Teams
- Two or more teammates need to compare or challenge each other
- The answer requires synthesis across separate angles
- You can run the whole team in one sitting
- You have checked usage and can afford full separate instances
Keep Secrets Out and Costs Visible
An idle teammate is still a full Claude Code instance on your plan, so the last two checks before scaling are what you paste and what you spend. Never paste passwords, client files, or medical or financial records into a Claude Code session.
On free and personal plans, chats may be used to improve the company's models unless that is switched off in settings. Check that toggle before the first team run, not after.
What it costs as of November 2026: Claude Pro is $20 a month, or $17 a month billed annually, and includes Claude Code.
Max is $100 a month for 5x usage or $200 for 20x. Team seats are $25 or $125 a month. Confirm current limits on Claude's own pricing page.
Token cost rises with every teammate, because each one is a separate instance holding its own context. A run that hits the claude.ai usage limit pauses rather than fails. The waiting agents resume once the limit resets, on Claude Code v2.1.271 or later.
So run three teammates on a low-sensitivity public document first. Check usage when the lead returns its table. Add the fourth only if the numbers say the argument was worth the bill.
Worth noting: that first small run also tells you how fast your plan drains, which no estimate will.
Frequently Asked Questions
Do I need to know how to code to use Claude Agent Teams?
You need to edit settings.json or set an environment variable to enable the flag, which is one line. Writing the lead brief is plain English. Reading terminal output is the main skill that helps.
Is Agent Teams the same as subagents?
No. Subagents are helpers inside one session that only report to the main agent and cost fewer tokens. Agent Teams spawns independent instances that message each other directly, with token cost rising per teammate.
What happens if I hit my usage limit mid-run?
Claude Code pauses the run rather than failing it. Waiting agents run again after the limit resets, and the run continues on Claude Code v2.1.271 or later.
Can I pause a team run and resume it tomorrow?
There is no session resumption with in-process teammates. Plan the run as one sitting, or break the work into separate runs with their own briefs.
How many teammates should I start with?
Three to five, with 5 to 6 tasks per teammate, per Anthropic's docs. Four teammates and five tasks each is a reasonable first run.
Is it safe to run on private files?
Do not paste passwords, client files, or medical or financial records into a chatbot. Run the first team on a low-sensitivity public document and check the output before using anything private.
One Session or a Team: The Rule to Run First
Choose one Claude session or subagents for a single answer, or any task one assistant can finish in one pass. Choose a 3- to 5-teammate Agent Team only for work that needs parallel review, challenge, and synthesis.
The first action is small: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, run the four-teammate, five-task sample brief on a low-sensitivity public document, and check the usage afterward. Add a fifth teammate only when the four have earned it.
The same instinct applies to habits: start with a few Claude tricks power users rely on before stacking more setups.
The same question runs through every step: what does the extra teammate buy that the lead alone cannot?
If the answer is another opinion on the same document, keep the session. If it is a real disagreement that changes the output, the team pays for itself.