Claude Agent Teams: Coordinating Several Sessions

Snapshot of the documentation and the product: 10 October 2026.

Several agents can investigate different parts of a problem at the same time, but parallel work on its own does not mean a faster or better result. For their work to add up to one verifiable outcome, you need boundaries, owners, shared agreements, synchronisation, access control and an integration review. Without them, what grows in parallel is not only the volume of work but also the number of contradictions, repeated reads and decisions that a person has to check.

This unit is specifically about Agent Teams in Claude Code: a team of separate Claude Code sessions coordinated by a lead session. As of 10 October 2026 the official documentation marks the feature as experimental and disabled by default. It can be enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in Claude Code's settings or environment. The latest release in the changelog on the snapshot date is v2.1.296 from 9 October 2026. That number describes the client available on the snapshot date, not the minimum version required for every team feature. Check the documentation and your installed version before using this on a project. [1][2]

A team, subagents and several independent sessions are different models

Claude Code offers three ways to bring in more than one model session. They differ in where the context lives, how results are passed on, and who coordinates the work.

Way of working	What happens	When it may fit	Main limitation
Subagent	A separate child task inside the current session. The subagent has its own working context and returns its result to the caller.	A bounded investigation, check or subtask that can be handed off and then collected in the main session.	Not a full collective with its own coordination: the main session remains the place where everything is consolidated.
Agent Team	A lead Claude Code session organises separate member sessions (teammates), a shared task list and messaging. Teammates have separate contexts but work on a shared project.	Several independent areas of analysis or change, where direct communication between teammates and task coordination are useful.	A shared project does not automatically become isolated: files, working state and external resources can conflict.
Manually coordinated sessions	A person or a process launches separate sessions independently and carries instructions and results between them.	When you need manual control, different environments, or an explicit separation of stages.	There is no Agent Teams shared task list; reconciliation, state transfer and retries are the coordinator's responsibility.

So a subagent is not the same as an Agent Team member. A subagent usually carries out an assignment within a single session; a team member is a separate session with its own context and messages addressed to it. And several Claude Code windows do not, by themselves, make an Agent Team. The documentation also warns that in team mode Claude Code may turn a named subagent into a team member even if the user did not explicitly ask for that; the mere appearance of the team panel does not prove that this has happened. [1][3]

Agent Teams are available for interactive use of Claude Code. In non-interactive mode, including runs with the -p flag, and in the Claude Code software development kit (SDK), Claude Code does not launch Agent Team members and falls back to ordinary subagents. The display mode matters too: the standard mode shows several teammates in the same terminal, while split panes depend on tmux (a terminal multiplexer, which arranges several terminal sessions in one window) or iTerm2. The official list of limitations names Windows Terminal, the Visual Studio Code terminal and Ghostty as incompatible with split panes. This is a display limitation, not evidence that Agent Teams themselves only work with tmux or iTerm2. [1]

First decide whether you really need a team

Before splitting the work, answer some simple questions. Could it be finished in a single session without losing quality? Are there genuinely independent sources or areas of change? Can the boundaries be fixed so that teammates do not edit the same file or make separate decisions about one shared schema? Will a person have enough time to check all the results?

If the task is sequential (first define the product rule, then write the code, and only then check the migration), splitting it among several workers can create waiting and rework. If the subtasks are independent, for example separate readings of the documentation, a check of how an application programming interface (API, a formalised way for one program to call the functions of another) is used, and an analysis of test scenarios, a team can shorten the time to the first consolidated conclusion. That is only a possibility, not a guarantee: teammates may spend time on the same context, miss a dependency or fail to reconcile their results.

A clear subtask contract answers these questions:

Contract field	What to pin down
Goal and boundary	Which question to answer; what is outside the task.
Input state	Which commit or other revision the conclusion is based on; which files and sources to read.
Owner	Who is responsible for the result and to whom it is handed.
Permissions	Reading, editing, running checks or taking external action; and, separately, what is forbidden.
Invariants	Which rules are shared by everyone: data format, state semantics, compatibility, the boundary on external side effects.
Output and evidence	The response format; specific files, lines, sources, check results and unknowns.
Completion condition	What evidence is needed to say "done"; how to report a blocker or a contradiction.

The phrase "investigate the migration" does not say whether the teammate may change the database. It is better to be specific: "Read the current schema and migrations at revision D7; change nothing and do not connect to the live environment; describe the possibility of duplicate keys, give files and lines, and separate confirmed facts from assumptions." A clear boundary lets the coordinator compare results without guessing what was actually done.

Teammates need enough instruction to work on their own, but not the lead session's entire conversation history. They do not inherit its earlier dialogue; they do receive the project's shared settings, including CLAUDE.md, the configured Model Context Protocol (MCP) servers, and Skills. So the contract must contain the needed context directly, and the project's shared rules should be kept where teammates can actually read them. Do not forward the full chat instead of a concise state, the decisions made and links to verifiable material. [1]

Coordination: owners, messages and evidence

In the current implementation the lead agent creates the team and keeps the coordinator role; a teammate cannot become the new lead of that team, and a nested team inside a teammate is not supported. Teammates can talk to each other directly, and the shared task list shows what is pending, the dependencies and the states. These capabilities depend on the task tools available to a particular session; not every environment has the same tooling. [1]

A useful message is not "done" but a short, evidence-backed record:

Checked usage of POST /reservations at revision D7. In web/src/reservations.ts:48 the request passes an idempotency key; in jobs/import-reservations.ts:112 it does not. Did not change any files. I don't know whether the batch importer should create such a key: that needs a product decision. Summary and list of paths are in the reply to the "API usage" task.

Here the revision defines the baseline of the observation; the file and line let anyone open the same evidence; the statement about actions taken separates investigation from change; and the unknown is not dressed up as fact. If another teammate has already done the work, or new information has appeared, the coordinator should say so briefly and explain what decision or check is needed next.

It helps to distinguish four kinds of message:

1. Observation: what exactly was read or checked, with the revision and source.
2. Decision needed from the coordinator: what is blocking the work, what the options are and the consequence of each.
3. Handoff: which files or evidence are ready and who has to act now.
4. Completion or failure: which part of the defined contract was met, what was not, and what remains unknown.

A teammate should not mark a subtask complete just because it has finished reading. The owner completes it when the agreed result and evidence have been delivered. The lead session independently checks whether the evidence is current, whether it matches the contract and whether integration is needed. According to the Claude Code documentation, task-list statuses can lag; a received message or a completed label is a signal to check, not the check itself. [1]

This distinction matters for historical reports as well. In August 2026 a user described a problem on GitHub in which a background teammate's final text response never reached the lead session; instead, only a content-free "done" notification arrived. The report named specific versions and the reporter's own environment, not all teams, and the issue itself was closed as not planned. Anthropic's changelog for v2.1.251 from 28 August separately describes a fix for the same symptom, but does not reference that issue. So the correct conclusion is that this is a historical signal for why you should require an explicit result and check it; it is not evidence of a current defect in v2.1.296, nor confirmation that this particular issue prompted the fix. [2][7]

Splitting and synchronisation

Fan-out/fan-in is a pattern in which the coordinator hands out several independent subtasks and then gathers their results into one decision. It is useful only when the dependencies are visible in advance. For example, the investigation of the API, the migration and the tests can start in parallel, but creating a unique index has to wait for a confirmed rule on how to handle existing duplicates.

Set a checkpoint for each stage: what must be known, who consolidates the evidence, and which decisions block the next step. A research stage can end with a short report; implementation, with changes agreed by contract; integration, with checks against a specific new revision. Do not merge these states into one shared "almost done".

Readiness is tied to a specific revision. If the checks were made against D7 and the file changed in D8, the claim "checked" does not carry over to D8. The consolidated conclusion must say what exactly was checked against which state, what has changed since, and which evidence needs refreshing. Several teammates having worked at the same time does not make their independent results consistent.

A shared environment means shared risks

A separate conversation context does not mean a separate workspace, separate data or separate external powers. Claude Code describes a team as several sessions working in one project. The documentation specifically advises avoiding conflicting edits to the same file: teammates who change it at the same time can overwrite each other. So split files among owners, or assign one owner to a shared file and make the others readers or reviewers. Do not assume that Agent Teams automatically creates an isolated branch or worktree for each teammate. [1]

The same planning is needed for every shared resource those sessions can reach: a database, a test account, a queue, a local process, a port, build files, provider limits or an external service. One teammate can wipe a table while another is measuring its state; two can launch the same migration process; five sessions can exhaust a shared request quota. These are risks of a shared environment, not a claim that every Claude Code installation has a particular database connection or shared process.

Before allowing side effects, assign a single executor for each resource. Fix the test data, the recovery method, the time windows and the safe limits. For verification, choose an isolated copy or read-only access if that is sufficient; leave live changes to a separate process with an owner and a verifiable approval. Several sessions must not run a migration, a clean-up or the creation of external resources at the same time just because the task list makes it possible to split that work.

Delegation does not expand authority

It helps to consider three things separately: the textual assignment, the tools' actual access, and the boundary beyond which a person's approval is required. A prompt can say "do not change files", but the text is not a system-level access control. Conversely, a tool that has been granted may permit changes the task's author never intended. Claude Code's real rules are enforced by the product, not created by a single instruction to the model; external authentication and service restrictions are separate layers. [4]

In the current documentation, teammates inherit the lead session's permission mode, except for dontAsk mode; if the lead session uses --dangerously-skip-permissions, every teammate inherits it. You cannot set a separate permission mode for each teammate at creation time, although it can be changed later. Permission requests from a teammate are routed to the lead session, where approval belongs to the person. A teammate's message cannot substitute for the user's consent or get around a refusal. There is an important subtlety: approval of the team's plan is granted automatically by Claude in the lead session, without prior review by a person, so it should not be presented as human approval. [1]

Before fanning out, fix a matrix of actions, not just a role: reading files; editing; running local checks; access to external systems; publishing, merging or deploying; using secrets. If a teammate can write data to an external system, separately restrict the identity, scope, environment and approval. The coordinator must not approve a risky action "on behalf of" the worker if that action needs the system owner's consent.

Failures, retries and shutting a team down

During coordination you may lose a teammate, get an incomplete result, see an action repeated, receive conflicting advice, or be blocked on an external dependency. The recovery plan has to tell these cases apart:

Situation	Safe next decision
A teammate stopped responding	Record the last known revision and state; check for partial changes; assign another owner only after checking those changes.
A partial result	Ask for the finished and unfinished parts, the next piece of evidence needed and the blocker to be named; do not treat an interim report as completion.
A repeated action	Find out whether the action is idempotent (repeating it changes nothing beyond the first run); if not, check the state of the external resource before retrying.
Different conclusions	Compare sources, times and revisions; ask the contract's owner to resolve that specific disagreement rather than averaging conflicting answers.
Stop or cancellation	Stop new actions; check active processes and partial external effects; assign an owner to them and clean up only through a defined procedure.

Claude Code also documents specific current limitations: one team per session; the lead role cannot be transferred; a team session with teammates cannot be resumed as a finished team; task status can lag; a request to shut a teammate down may wait until it finishes its current tool call; nested background subagents launched by teammates are not supported. These facts matter for the recovery plan: do not rely on waiting indefinitely or on the whole state being restored automatically after an interruption. [1]

A retry is appropriate when it is clear that the previous action finished without an unwanted effect, or that it is safely repeatable. Before retrying, check the revision and the shared files; two copies of a change can be harder to notice than one explicit conflict. When the work is finished, report which teammates have been shut down, which partial changes were accepted or rejected, whether any processes are still running, and who owns any resources that have not been cleaned up. The end of a conversation does not prove the end of a side process.

Why an integration review remains mandatory

Each partial result can be locally correct and still incompatible with its neighbour. One teammate treats unknown as a safe refusal, another as a success state. The API investigation may rely on an old revision while the test review already uses a changed one. So the lead session or the human owner has to review the set of changes as a whole: shared data types, invariants, calls, migrations, tests, errors, external effects and evidence against the current revision.

The team's status, the number of completed subtasks and the volume of text produced measure activity. What has to be assessed is the usefulness of the accepted result: does it meet the requirements, does it pass the appropriate checks, does it avoid creating conflicting contracts, and how much time went into fixes and human review? Do not reduce productivity to the number of messages or parallel sessions.

Boundaries as questions for people, not an "org chart of agents"

In the second edition of Team Topologies, Matthew Skelton and Manuel Pais describe teams' cognitive load, team boundaries and the ways teams interact. Here these ideas can be used only as questions about the design of the task. Does the subtask have an understandable context? Which team or role owns the shared contract? Where is collaboration needed, and where is it enough for one side to deliver a result as a service? Do not assign the book's formal human team types to sessions, and do not conclude that an organisational diagram proves Agent Teams are effective. Only the authors' and publisher's public materials were consulted; the full text of the book was not checked. [5]

In The Mythical Man-Month, Frederick Brooks drew attention to the mistake of treating person-months as interchangeable and of confusing effort with progress. As a cautious question about agent work, this can be put as follows: does the split actually shorten the critical path, or does it add the cost of explaining, reconciling and consolidating? This is a question carried over into another context, not an empirical law about the speed of agents. The openly available excerpt and the publisher's materials give no grounds to claim that the whole book was read or that it studied modern models. [6]

Worked example (fictional): investigating an API, a migration and tests

Situation. A hypothetical booking service needs to support resubmission of an identical request. The task is to work out how to add an idempotency key to POST /reservations without creating duplicates when a request is retried after a network timeout. In the example the team works against the hypothetical revision D7. As a reminder, an API (application programming interface) is a formalised way for one program to send a request to another.

Problem. A single session might spend its time on three different reviews and propose an implementation prematurely, before it understands the existing data. If three teammates edit one controller, one table and the tests without a shared agreement, parallelism turns into conflict.

Alternatives. For a small, familiar service the lead session can read these three areas one after another. If only a decision on the contract is needed, one short analysis without a team is enough. A team is justified when the searches in the different areas are genuinely independent and the coordinator needs all the results before choosing an implementation.

Action and contracts. The coordinator creates three separate research subtasks and forbids changes and connections to the live service in all of them:

Owner	Boundary	Required result
API investigator	Only the paths that build POST /reservations at D7	The files and lines of every client; whether the key is passed; what the client does after a timeout; unknowns.
Migration investigator	Only schemas and historical migrations at D7	Conditions for a unique key; duplicate risks and backward-compatibility requirements; no migrations are run.
Test investigator	Only tests and fixtures at D7	Which cases are already checked; what covers a repeated request and a concurrent request; missing evidence.

Observed result. The illustrative reports find that the web client passes the key but the batch importer does not; historical records contain duplicates that could violate a unique index; and a test checks a sequential retry but not simultaneous identical requests. The coordinator consolidates these not into "safe to migrate" but into three verified facts and one open question: should the importer create a key, and what should happen to the existing duplicates? Until the product owner answers, the migration and the code stay blocked. Once the rule is defined, one designated schema owner updates the migration and the code on a new revision; another teammate checks the web and batch scenarios and the race between concurrent requests. The result is accepted only after the changes have been consolidated and checked against that new revision.

Why this approach fits. The three areas can be investigated in parallel, but the compatibility decision depends on a shared fact about historical duplicates. The contracts prevent the investigators from making accidental changes, and the owner of the product decision stays visible.

Limits. All the names of the service, results, files and revisions in this scenario are invented for teaching. This split does not guarantee a shorter overall time: waiting for the product decision or a conflict in the test environment will still be there. If a criterion can only be checked on live data, the team must stop changes until safe access is available, rather than interpreting the lack of access as the absence of duplicates.

Worked example (fictional): two incompatible data types

Situation. A hypothetical delivery service wants to add transaction statuses. Two teammates implement this change independently. The first treats captured and failed as the canonical values; the second expects only settled and declined.

Problem. Both teammates edit consumers of the shared DeliveryState type. The first implementation puts an unknown value into an error state; the second treats any unknown value as success. Each local test passes under its own assumptions, but the boundary between the services is now dangerous.

Alternatives. You could give up on parallel implementation and assign all the changes to one owner. Or you could define the data type first and only then split up the independent consumers. The choice depends on whether the teammates can name and accept one contract before editing.

Action. The coordinator stops both changes and points out the contradiction with references to the specific files and revisions. The owner of the product/schema contract defines the full list of allowed states, the transitions between them and how an unknown value is handled; for this example, the decision is that an unknown value must not be treated as success. Then one teammate becomes the sole owner of the DeliveryState definition, and the other gets a bounded task: update the interface display and add a test for an unknown value, without changing the shared type. The coordinator checks every reference to the type, the consolidated changes and the tests on a single new revision, R4.

Observed result. In this example the conflict is no longer hidden behind two sets of locally passing tests. A fixed contract, one authoritative type and a test for the unknown value show how consumers behave outside the expected cases. The "done" status is granted only after all calls and results have been checked on R4.

Why this approach fits. The shared type is the point of agreement. Its definition belongs to one owner; after that, other teammates can work in different areas without creating alternative interpretations. The official Claude Code documentation explicitly advises distributing work so as to reduce the chance of simultaneous changes to the same file. [1]

Limits. The whole scenario is fictional. If the type is generated from a schema, or the contract belongs to another team, editing the file by hand is not the source of truth: you have to change the controlled schema and apply its rules. A single file owner also does not settle whether the chosen statuses are correct; that needs a domain owner and integration evidence.

Worked example (fictional): five agents fix one typo

Situation. In one line of a text notification, the word "confirmation" is printed with a missing letter. The spelling needs to be fixed without changing any behaviour.

Problem. The coordinator proposes bringing in five teammates: find the line, check the locale, review the style, assess the test, and independently verify the result. The task is tiny, and the conclusions are easy for one owner and one short review to check.

Alternatives. One author can fix the line and another person can read the diff. If the text is part of a regulatory notice, or a shared translation dictionary is being changed, a broader review may be justified, but then you must name the specific risk that each additional teammate checks.

An illustrative cost calculation. All the numbers below are invented assumptions for demonstration; they are not a Claude Code measurement, a token price or a benchmark. For a single session, assume 8 thousand tokens of context and two minutes of human review. For five teammates, assume 5 thousand tokens for the brief and coordination, 6 thousand for each teammate that separately reads the file and the rules (another 30 thousand), and 7 thousand for consolidation and the integration review. That is 42 thousand in total, 5.25 times the baseline 8 thousand. If a person also reads each of the five reports, assume eight minutes of review instead of two. The result is the same: one character fixed and a checked diff.

Action and outcome. The coordinator declines to fan out to five sessions. One owner makes the targeted change, and one reviewer checks the spelling, the absence of unrelated changes in the diff, and the required text check. In this teaching example those steps take less context and attention, and every conclusion has visible evidence in the diff.

Why this approach fits. Parallelism pays off when the work is large and independent enough to recoup the cost of building context, coordinating and verifying. For a one-character fix, that cost dominates the task.

Limits. The calculation must not be carried over to other tasks or versions as a measure of productivity. If a single typo affects a critical legal text, five independent checks may reduce a specific risk, but that decision must be justified by that risk, not by the general idea that "more agents means faster".

A short checklist for designing an Agent Team

Before launching a team, the lead session or the human coordinator can pin down the following:

1. Name the end result, the boundary of the work, and what is explicitly outside it.
2. Check that the subtasks are independent, large enough and have clear owners.
3. Fix the shared base revision, the data contract, the invariants and the owner of shared files.
4. For each teammate, state the permitted actions, the forbidden side effects, the sources needed and the exact evidence format.
5. Define dependencies, consolidation points, blockers, safe retry conditions and who owns partial resources.
6. Tie every readiness claim to the current revision and check all the results together.
7. Judge not the volume of parallel work but the accepted result, the cost of coordination and the time spent on human review.

If you cannot say who owns the shared contract or how completion will be verified, the subtasks are not yet ready to hand out. Start by clarifying the boundary or by running a sequential stage. Once the uncertainty is resolved and several genuinely independent streams remain, a team can be a useful way to cut waiting time. Keep a person responsible for authority, the product decision and the final acceptance of the result.

Sources and further reading

The state of the product and of the current online pages was checked on 10 October 2026. The Claude Code documentation changes; the state described here should not be taken as a promise of features in any future version.

1. Anthropic, Orchestrate teams of Claude Code sessions, current online Claude Code documentation, accessed 2026-10-10. Used for the experimental status, setup, interfaces, team architecture, tasks and messaging, permissions, the shared workspace, limitations, cost, and coordination recommendations.
2. Anthropic, Claude Code changelog; release v2.1.296 from 2026-10-09 is the latest as of the access date, 2026-10-10. Agent Teams are mentioned as a research preview in v2.1.32 from 2026-02-05; the fix for the problem with a teammate's final response is described in v2.1.251 from 2026-08-28.
3. Anthropic, Subagents, current online Claude Code documentation, accessed 2026-10-10. Used for the difference between subagents and teams of sessions, and their limits.
4. Anthropic, Permissions, current online Claude Code documentation, accessed 2026-10-10. Used for the difference between system-enforced permissions and textual instructions; actual powers also depend on Claude Code's configuration and external authentication.
5. Matthew Skelton and Manuel Pais, Team Topologies: Organizing Business and Technology Teams for Fast Flow, 2nd edition, IT Revolution, 2025 edition; the author's page and short overview of the concepts, Key Concepts, accessed 2026-10-10. Only the public descriptions of cognitive load, team boundaries and interactions were used; the full text of the book was not checked. These ideas are not a model of AI agent states and do not prove the speed of Agent Teams.
6. Frederick P. Brooks Jr., The Mythical Man-Month: Essays on Software Engineering, Anniversary Edition, 2nd edition, Addison-Wesley Professional, 20th anniversary edition, 1995/1996; the publisher's open excerpt, Chapter 2: The Mythical Man-Month, accessed 2026-10-10. A limited available excerpt on confusing effort with progress was used; the full text of the book was not checked. Carrying this question over to agents is explicitly marked in this unit as a cautious analogy, not evidence or an empirical generalisation.
7. Anthropic, GitHub issue #86090: Named background teammate completes with a final text message that is never delivered to the parent, a public user report from 2026-08-12, accessed 2026-10-10. A single historical report about Agent Teams in particular environments and versions, closed as not planned; it does not prove the defect exists in the current version. The v2.1.251 changelog separately describes a fix for the symptom in which a teammate's final response did not reach the lead session and only a "done" notification arrived; the changelog itself does not name issue #86090, so no direct link between the two records is claimed. [2]
8. Anthropic, Claude Code v2.1.296 release notes, release from 2026-10-09, accessed 2026-10-10; used to establish the latest release on the snapshot date.