OmniscioGuidesClaude Code agent teams
Claude Code agent teams: what they are and how to run one
Written from Anthropic’s documentation as read on November 11, 2026, when the latest Claude Code release was 2.1.322. Not run by us. By the Omniscio team. Updated .
Start here
- Turn it on: the setting, and where it does nothing.
- Teams or subagents: the table.
- Your first team: the prompt and the panel.
- A pane each, and tmux.
- What holds a team together: task list and mailbox.
- Steering: a plan first, who approves permissions.
- Broken: the errors word for word.
- Limits: the list Anthropic publishes.
Turning agent teams on
Agent teams are experimental and off by default. Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, in your shell or under env in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}The session you are in becomes the lead. Teams also change ordinary delegation: a subagent Claude names to message later starts as a teammate unless the call is a fork or passes isolation, so teams form from delegation you never framed as team work.
Teams also need an interactive session: with -p, including Agent SDK sessions, Claude spawns no teammates at all, and a named subagent runs as an ordinary subagent even with the variable set.
Anthropic’s warning calls the feature experimental and lists known limitations around session resumption, task coordination and shutdown behaviour; read the limits section first. To turn teams off, set the same variable to 0.
Agent teams or subagents
Anthropic’s comparison lists five routes: subagents, agent view, agent teams, projects and dynamic workflows. Subagents and agent teams get confused because both run Claude several times; a subagent works inside your session and reports back, a teammate is a separate session that messages the others itself.
| Subagents | Agent teams | |
|---|---|---|
| Context | Own context window; results return to the caller | Own context window; fully independent |
| Communication | Returns a result to the caller. Subagents Claude named when it spawned them can also message each other | Teammates message each other directly |
| Coordination | The main agent manages all the work | Self-coordination through messages, plus a shared task list for agents that have the Task tools |
| Best for | Focused tasks where only the result matters | Complex work needing discussion and collaboration |
| Token cost | Lower: results are summarised back into the main context | Higher: each teammate is a separate Claude instance |
Anthropic names four shapes where a team earns its cost: research and review, where teammates investigate different angles and challenge each other; a new module or feature, each owning a separate piece; debugging, competing hypotheses tested at once; cross-layer work spanning frontend, backend and tests. The common thread is that the work divides cleanly.
Teams add coordination overhead and use significantly more tokens; for sequential tasks, same-file edits, or many dependencies, one session or subagents do better. No figure is published: each teammate is its own context window, and usage scales with active count and runtime.
Starting a team
With the variable set, describe the task and the teammates you want; Claude fills a shared task list, spawns a teammate per part, and synthesises the findings. The lead names them on spawn, so put the names you want in your prompt to address later.
I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.The three roles explore without waiting on each other. Anthropic’s guidance: three to five teammates for most work, each task a self-contained unit with a clear deliverable, five or six tasks per teammate; three focused teammates often beat five scattered ones.
The agent panel sits below the prompt input: arrows select a teammate, Enter opens its transcript to type into, Escape clears the selection. An idle row stays visible while any other agent works; once all are idle, rows hide after 30 seconds and return on that teammate’s next turn, still running and messageable.
More than three idle fold into one row: five idle shows 2 idle agents, which Enter expands.
Claude may reach for subagents instead of a team, and they appear in the same panel, so the panel alone does not confirm a team formed. If you wanted one, say so and ask again.
In one terminal, or a pane each
Two display modes: In-process (any terminal, the default) and Split panes (a pane each: watch them all, click one to type).
| Setting value | What you get |
|---|---|
in-process | Everyone inside your main terminal. The default, and needs nothing installed. |
auto | Split panes when you are already inside a tmux session, or in iTerm2 where it2 is on your PATH or tmux is installed; in-process otherwise. |
tmux | Split panes, auto-detecting tmux or iTerm2 from your terminal. |
iterm2 | iTerm2 native split panes through the it2 CLI. Shows an error with the install command if it2 is missing. |
Set it in ~/.claude/settings.json as teammateMode, or for one session with claude --teammate-mode auto, an experimental flag absent from claude --help. You can also pick it in /config under Teammate mode.
Split panes mean tmux: Anthropic notes known limitations on some operating systems, traditionally best on macOS, with tmux -CC in iTerm2 the suggested way in. Split panes are unsupported in VS Code’s integrated terminal, Windows Terminal and Ghostty.
On November 11, 2026, a GitHub search of anthropics/claude-code issues titled “agent team” returned 446 results all-time; the most-reacted asks for the zellij terminal multiplexer as a split-pane backend (#24122, opened February 8, 2026, 96 reactions, still open), then Ghostty and Windows Terminal.
What holds a team together
An agent team has four parts: the lead (your main session), teammates (each a separate Claude Code instance), a task list they claim from, and a mailbox each.
The shared task list
Tasks move through three states: pending, in progress, completed. A task can depend on others and reads as blocked until they finish; a teammate will not claim a blocked one on its own, though you or the lead can assign it. Otherwise the lead assigns work, or a finished teammate takes the next unassigned, unblocked task.
File locking stops two simultaneous grabs both winning. Agents without the Task tools use messages.
The mailbox
Each agent’s mailbox is a JSON file at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Messages arrive automatically; the lead does not poll. Every entry is validated on read: a malformed one is reported as an error and removed, while valid neighbours still deliver.
Sent means the write to the recipient’s mailbox succeeded, plain text or a protocol message such as a plan approval or shutdown request.
The team and its task list live under a name derived from your session: session- plus the first eight characters of the session ID. The config at ~/.claude/teams/{team-name}/config.json is removed when the session ends; the task list at ~/.claude/tasks/{team-name}/ stays on disk, with cleanupPeriodDays deciding how long.
The config holds runtime state such as session IDs and tmux pane IDs, so never edit or pre-author it: changes are overwritten on the next update. There is no project-level version: a .claude/teams/teams.json in your repository is an ordinary file.
Read it anyway: its members array holds names and agent IDs, and the lead always carries the agent type team-lead.
What each teammate starts with
A new teammate loads the project context a normal session would: CLAUDE.md, your MCP servers and your skills; a lead started with --setting-sources gives teammates that same restricted list. Your conversation does not carry over, so the spawn prompt is the teammate’s only account of the task; put the task-specific detail in it.
Spawn a teammate from an existing subagent definition by naming it, for example spawn a teammate using the security-reviewer agent type: that reuses its tools, model, disallowed tools and body, and an in-process teammate also gets SendMessage.
The model is the first of: the one your prompt names, the definition’s model (inherit means the lead’s), CLAUDE_CODE_SUBAGENT_MODEL unless set to inherit, otherwise the lead’s current model.
Steering a team while it runs
Each teammate is a full, independent Claude Code session, so you can message any directly instead of through the lead. In in-process mode, select it and press Enter, then type.
While you are viewing an in-process teammate, plain text and skills go to that teammate and built-in commands go to the lead, with two guards: /compact, /clear and /rewind act on the lead’s conversation and ask you to confirm first; /model and /fast set the lead’s model and do not run from that view.
A teammate’s model and fast mode are fixed at spawn.
Get the plan before the code
Put the lead in plan mode first, then ask for the teammate; it stays in plan mode until its plan is ready, then sends a plan approval request.
If that teammate’s permission mode has not changed since spawn, Claude Code approves the plan the moment it arrives, without the lead reviewing it. Put a running in-process teammate into plan mode with Shift+Tab while viewing its session, and the lead reviews that run’s plan instead, approving or sending it back.
Permissions follow the lead
You cannot set a teammate’s permission mode at spawn: it starts in the lead’s mode, including bypassPermissions when the lead ran with --dangerously-skip-permissions; a lead in dontAsk mode starts its teammate in Manual instead (split panes need v2.1.317+).
An in-process teammate runs under the lead’s live allow and deny rules, so --disallowedTools, --tools and --allowedTools all apply; a split-pane teammate gets the deny rules and tool list from v2.1.309 on, but not --allowedTools. Permission prompts appear in the lead session: approve them there, and pre-approve common operations.
One safety restriction: Claude Code tells the receiver a message came from another Claude session, not from you, so a teammate cannot answer a permission prompt for you, and a refused teammate cannot relay the action to another to get past the check.
In auto mode the classifier treats relayed approvals as untrusted and reviews every message before delivery, shutdown requests included.
Three hooks fire on team events, enforcing rules as a teammate stops: TeammateIdle when a teammate is about to go idle, TaskCreated as a task is created, TaskCompleted as one is marked complete. Exiting 2 from any blocks the action and hands your stderr back as feedback. The hooks guide covers the mechanics.
To end a teammate, name it, for example ask the researcher teammate to shut down; the lead sends a shutdown request, and the teammate approves and exits or rejects it with an explanation.
When a team will not form, or goes wrong
The task may have been too small for Claude to judge a team worth building, or the rows are hidden: idle rows hide 30 seconds after the panel goes idle and return on that teammate’s next turn. For split panes check which tmux; for iTerm2 that the it2 CLI is installed and the Python API enabled.
The opposite happens too: a subagent Claude names starts as a teammate. Set the variable to 0 to turn that off, no new session needed: Claude Code rereads a settings-file value on each subagent spawn. A 0 in user settings.json overrides a shell export, but a project, local, --settings or managed setting saying 1 wins.
| What you see | What it means | What to do |
|---|---|---|
Failed to write to <name>'s inbox — nothing was sent | Claude Code could not create or update that teammate's mailbox file: the disk is full, the directory is not writable, or another agent held the inbox lock too long | Clear the disk space or the permissions problem and send it again. Nothing went out, so there is no half-delivered message to clean up |
Couldn't write to @name's inbox — message not sent. Try again. | The same failure, seen when you typed @name and the message yourself | Send it again: Claude Code keeps your text in the prompt box |
Failed to write the plan approval request to the lead's inbox — plan not submitted | The teammate's plan never reached the lead, and the teammate stays in plan mode | Resubmit it |
The permission request could not be delivered to the team lead (mailbox write failed) | A teammate's permission request never reached the lead, so nobody approved the tool call | Fix the mailbox write failure first; the request has to be made again |
Only a teammate can approve a shutdown request | The session that sent the approval is not running as a teammate | Ask the lead at its prompt to shut that teammate down |
A command-line deny rule cannot be handed to a teammate intact | A split-pane teammate would have read one of your command-line deny rules differently and would not have enforced it, so the spawn was aborted | Run /config in the lead and set Teammate mode to in-process, then spawn it again. An in-process teammate runs under the lead's live deny rules |
Its agent definition was not restored: the folder its definition file came from is not trusted | Claude brought a stopped teammate back without the subagent definition it was spawned from | Run claude in the folder named in the debug log and accept the trust dialog. The definition is re-applied the next time Claude Code brings the teammate back; the lead does not need restarting |
Two more symptoms are not errors. Teammates sometimes stop early after hitting a problem rather than recovering: select it, read its output, then give more instructions or spawn a replacement. A message from the lead wakes an in-process teammate awaiting an API retry, so it retries at once.
If a tmux session outlives Claude Code, tmux ls lists it and tmux kill-session -t <name> ends it.
Before v2.1.224, a message whose mailbox write failed was still reported to the sender as sent.
What agent teams cannot do yet
- No resumption.
/resumeand/rewinddo not restore in-process teammates. After resuming, the lead may try to message teammates that no longer exist; tell it to spawn new ones. - Task status can lag. Teammates sometimes fail to mark a task completed, which leaves dependent tasks blocked. Check whether the work is done, then update the status or ask the lead to nudge it.
- Shutdown can be slow. A teammate finishes its current request or tool call first.
- One team per session, and no nesting. A session has exactly one team, scoped to it, and a teammate cannot spawn its own. Only the lead manages the team, and the lead is fixed for the session’s lifetime: you cannot promote a teammate.
- No background subagents from a teammate. An in-process teammate’s own subagents run in the foreground, because a teammate’s background work cannot outlive the lead’s process.
- No per-teammate permission mode at spawn. Teammates start in the lead’s mode (above).
- Split panes need tmux or iTerm2, and do not work in VS Code’s integrated terminal, Windows Terminal or Ghostty.
One limit is not on that list but follows from the architecture: agent teams do not isolate teammates in worktrees. two teammates editing the same file overwrite each other, so each must own a different set of files.
Anthropic’s parallel-work comparison: a worktree gives each session a separate checkout, and agent teams do not isolate teammates that way at all.
Where this page stops
- One delegated worker inside one session. A subagent; the subagents guide owns it.
- Several sessions you run side by side with no coordination. The parallel agents guide covers that.
- Two separate sessions passing findings. Cross-session messaging, needing no team and no lead.
- The whole map. The orchestration guide compares all five routes; this page owns the team: the lead, the shared task list, the mailbox, and what centralised management means.
Omniscio crews, and the same idea over a different wire
Omniscio’s closest equivalent is crews: a team of agent sessions working one mission in the same two roles, a lead (the crew’s overseer) and members, named in src/shared/agent-crew.ts:89, where src/shared/agent-crew.ts:95 gives the lead the role overseer. The app gives the lead a heartbeat every 15 minutes and a deeper review every 6 hours.
- A report goes to the lead, not to you. When a member finishes a turn, its report and questions go to its lead as a message instead of your inbox. It reports to the crew’s lead, or to a member the lead chose; the app reads that from the registration, not the session’s title (
src/main/services/crew/agent-crew-index.ts:231, falling back tocrewLeadOfat:205). - The task list has more than three states. A crew task is
todo,doing,waiting,blocked,doneordropped(src/shared/agent-crew-mission.ts:48). The first four are open; the two closed ones need an outcome, and any move carries a note saying why (src/main/services/crew/agent-crew-mission-core.ts:35and:45). - One private board. Only a crew’s lead and live members can read or post to its board; outsiders are told it does not exist. A member reads it before starting and posts what the crew must follow.
- The team outlives a session. Claude Code’s team config is deleted when its session ends, and its teammates do not come back after a resume. An Omniscio crew is an app record: a stopped member restarts, the lead passes to a successor, and the roster, tasks and board survive.
One terminal and an experimental team needs no app; a record that survives restarts, a board, and every report in one window is a crew. Omniscio’s agent crews page covers the roles, board and heartbeat.
Sources
- Orchestrate teams of Claude Code sessions: enabling, display modes, model selection, tasks, the mailbox, permissions, hooks, troubleshooting, limitations. Read November 11, 2026.
- Run agents in parallel: the five routes. Read November 11, 2026.
- Settings reference:
teammateModeand its four values, andteammateDefaultModelremoved in v2.1.234. Read November 11, 2026. - Errors: the mailbox-write and plan-approval failures, the shutdown approval refusal, the deny-rule spawn abort and the definition-not-restored notice, as quoted above. Read November 11, 2026.
- Hooks:
TeammateIdle,TaskCreated,TaskCompleted, and exit code 2 blocking the action. Read November 11, 2026. - Costs: how token use scales, and the advice to keep teams small. Read November 11, 2026.
- GitHub issues in anthropics/claude-code titled “agent team”: 446 all-time on November 11, 2026, plus the three split-pane requests above, read that day.
- Omniscio’s agent crews page, read on November 11, 2026, and the Omniscio source files cited here by line, read from master that day.
- Two checks on November 11, 2026: the npm registry’s latest
@anthropic-ai/claude-code, and the GitHub issue search above.
A preview feature that moves quickly: teammateDefaultModel was removed in v2.1.234 and a mailbox failure used to report success, so treat the version at the top of this page as the one described.
How we tested this
Every statement about Anthropic’s Claude Code was read from Anthropic’s own documentation on November 11, 2026, on the pages named in Sources. The release checked against is the one npm listed that day, 2.1.322; the issue count is GitHub’s search that day.
No agent team was started, no settings file edited and no message sent between teammates: this is Anthropic’s account, not ours.
Common questions
What are Claude Code agent teams?
A team of Claude Code sessions working one task together. One session is the lead: it plans the work, creates a shared task list, spawns the other sessions as teammates and puts the results together at the end. Each teammate is a full Claude Code session with its own context window, and teammates message each other directly rather than everything going through the lead. You can also message any teammate yourself. The feature is experimental and off by default: it runs only once CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to 1.
How do I turn on Claude Code agent teams?
Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either in your shell or under env in settings.json. Then ask Claude for the teammates you want in plain language, for example spawn three teammates to review this pull request from three angles. You also need an interactive session: with claude -p, including Agent SDK sessions, Claude does not spawn teammates at all, and a subagent that Claude names runs as an ordinary subagent.
Agent teams or subagents: which should I use?
Subagents when only the result matters: they work inside one session and report back to it, so they cost less. Agent teams when the workers need to share findings, challenge each other and coordinate: teammates message each other directly and share a task list, and each one is a separate Claude instance, so it costs more. For sequential work, edits to the same files, or work with many dependencies, a single session or subagents are the better fit.
Why can't I see split panes for my Claude Code agent team?
Split panes need tmux or iTerm2 with the it2 CLI, and the default display mode is in-process, which shows teammates in the agent panel under the prompt instead. Split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal or Ghostty. If you asked for split panes and got a single pane, check that tmux is installed and on your PATH, or set teammateMode to in-process.
How many teammates should an agent team have?
Anthropic's guidance is to start with three to five. There is no hard limit, but token use scales with the number of active teammates and coordination overhead grows with each one. Three focused teammates often beat five scattered ones, and if you have around fifteen independent tasks, three teammates is a reasonable starting point.
When a team needs to outlive the terminal
Omniscio runs Claude Code sessions side by side in one window, with the same idea built in: a crew with a lead and members, one shared task list with real statuses, every member’s report routed to its lead instead of to you, and a private board the whole crew reads.
A member that stops can be started again, and the roster, the tasks and the board are still there afterwards. The features page covers the rest, and you can download it for Windows, macOS or Linux. If the Claude Code feature is all you need, this page covers it, and the orchestration guide covers the other four routes.