How to Orchestrate Claude Code Agent Teams

When multiple developers run separate instances of a terminal agent in the same local directory, the instances operate in complete isolation. Without coordination, one instance will write a file while another is analyzing it, leading to code collisions and duplicated token costs. The solution is not to run them sequentially, but to deploy a unified team structure where a single lead coordinates specialized, parallel sessions.

Command line coding agents perform tasks by reading and writing files in response to terminal commands. When a project grows, running a single agent session becomes slow because the model must process the entire context sequentially. Developers often try to solve this by opening multiple terminal windows and starting separate agent sessions. This manual approach fails because the sessions do not communicate. If two agents attempt to edit the same file, they overwrite each other's changes without noticing, causing file conflicts and syntax errors.

To prevent these conflicts, you need a system that manages file access and coordinates tasks automatically. Instead of manual multi-instance setups, Claude Code introduces an experimental agent teams feature. This mode establishes a structured team where a lead session decomposes tasks, assigns them to specialized teammates, and coordinates execution. The teammates work in parallel without stepping on each other's writes, ensuring that edits are applied in a clean, predictable order.

• How to Setup Claude Coworking Workspaces for Research TeamsResearch teams often struggle with fragmented literature and disorganized data silos. Claude Coworking acts as a...
• How to Use OpenRouter with ClineUS search for "cline openrouter" is only about 40 queries per month (keyword difficulty 18), even though Cline lists...
• Everything Claude Code: The Complete Resource Guide for 2026Claude Code authored roughly 12% of all public GitHub commits by mid-2026, up from 4% just three months earlier. This...
• Claude Teams Plan Guide: Pricing, Cowork, and AdministrationAnthropic's Team plan supports 5 to 150 members with SSO, enterprise search across Google Drive, Slack, and Microsoft...
• How to Set Up SSO for Claude: Okta, Google Workspace, Entra ID, and OneLoginClaude supports SAML-based single sign-on on Team, Enterprise, and Console plans through Okta, Google Workspace,...
• How to Set Up Claude Cowork on Windows: Installation and ConfigurationThree GitHub issues filed against Claude Cowork in early 2026 report the same failure: Cowork refuses to start on...

More on this subject: Claude and Claude Code (159 guides)

Setting up agent teams requires activating the experimental flag in your local environment. Because this feature is currently in research preview, it is disabled by default. You can enable it for a single terminal session or configure it persistently for all future work.

To enable agent teams for your current terminal session, export the environment variable before launching the CLI tool:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude

For a persistent setup, you can add this environment variable to your shell profile, such as your .bashrc or .zshrc file. Alternatively, you can configure it within the global configuration file for the CLI. Open the settings file located at ~/.claude/settings.json and add the variable to the environment block:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

After saving the settings file, restart your terminal and launch the client. You can verify that the configuration is active by asking the agent if agent teams are enabled. The lead agent will confirm that the mode is active and that it can spawn parallel sessions to complete complex tasks.

Once you enable the experimental flag, you can control how the teammate sessions are displayed in your terminal. The CLI supports two modes for managing teammate outputs: in-process and tmux. Setting the correct mode is necessary for observing how different agents execute commands and edit files in parallel.

By default, teammates run in-process, meaning all sessions are managed within your main terminal window. You can cycle through the active teammates by pressing Shift+Down in your terminal. While this keeps your workspace uncluttered, it prevents you from viewing the terminal logs of multiple agents at the same time.

To watch teammates work in parallel, you can configure the display mode to use tmux. This setup automatically splits your terminal window into separate panes for each teammate. Edit your ~/.claude/settings.json file and add the teammate mode property:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "tmux"
}

This split-pane configuration requires you to run the CLI inside an active tmux session. When the lead agent spawns a teammate, the CLI creates a new tmux pane, allowing you to monitor the commands and file edits of each teammate in real time.

Using this setup introduces specific limits. Only one agent team can run per terminal session, and teammates cannot spawn nested teams. Additionally, teammates do not support session resumption, meaning you cannot run the /resume or /rewind commands inside a teammate pane. If a teammate fails, the lead agent must handle the error and reassign the task.

Coordinate your developer agents in one shared workspace

Get a central workspace with an MCP-ready endpoint for your agent's reads and writes, with per-file version history and meaning-based search built in. Every organization starts with a 14-day free trial, which requires a credit card. Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo.

Start 14-Day Trial

Orchestrating multiple agents requires a coordination layer to track progress and prevent conflicting edits. Unlike standard subagents, which operate in isolation and only report back to a parent session, agent teams use a shared task list and direct messaging to collaborate.

Each teammate in the team maintains its own independent context window of 1M tokens. Because they do not share a single context history, they do not suffer from context bloat when reading large codebases. Instead, they coordinate using two distinct mechanisms.

First, the team uses a shared task list stored locally in the .claude/tasks/ directory. When the lead agent breaks down a project into subtasks, it writes them to this directory. Teammates claim pending tasks by writing a claim record to the task directory, which prevents other teammates from working on the same files.

Second, teammates communicate directly via a local mailbox system. If a teammate needs to verify a function signature or discuss an interface design, it sends a message using the SendMessage tool. This direct communication allows teammates to resolve dependencies and verify code compatibility before merging changes.

This combination of task claiming and direct messaging ensures that agents do not overwrite each other's edits. By separating concerns, such as assigning backend API routes to one agent, database migrations to another, and testing files to a third, the team lead can parallelize development while maintaining codebase integrity.

When you deploy multiple agents to work on a codebase, local environments can become a bottleneck. Sharing code changes via local directories, git branches, or general storage services like Google Drive or Dropbox can lead to collaboration conflicts. These general services are built for human file sharing and lack the real-time indexing, search capabilities, and API endpoints needed for automated agents.

To resolve these collaboration conflicts, teams use Fast.io to provide a shared workspace. Fast.io serves as a persistent, collaborative file layer where both human developers and terminal agents can access files securely. Fast.io indexes files automatically on upload, making them immediately searchable using full-text and semantic search. To learn more about setting up these workspaces, visit the agent storage page.

For structured document processing, developers can use Metadata Views to define schemas for raw files. Teammates can query these views via MCP, allowing them to search files by metadata values or extract key data points without reprocessing the files.

To connect your Claude Code agent team to a Fast.io workspace, you can configure the Fast.io remote MCP server. Instead of running a local script or a custom file transfer client, you configure the agent to communicate with the Fast.io MCP endpoint at https://mcp.fast.io/mcp/key using your API key. Create a .mcp.json file in your repository root:

{
  "mcpServers": {
    "fastio-workspace": {
      "type": "http",
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      }
    }
  }
}

By exposing the workspace through this configuration, the lead agent and its teammates can read and write files directly in the cloud. Fast.io maintains a complete per-file version history, allowing you to audit edits and restore prior file versions if an agent introduces errors. For a complete list of endpoints and configuration details, refer to the Fast.io agent storage page. Because Fast.io manages granular folder permissions, you can restrict agents to specific paths, and transfer ownership of the workspace to a human manager when the task is complete.

Running multiple parallel agent sessions consumes a large number of tokens. Spawning a team of 3 to 5 teammates can quickly exhaust your API limits if the workflow is not optimized. Applying strict guidelines is necessary to keep costs manageable and ensure high-quality output.

To optimize token usage, you should limit your team size. Spawning more than 5 teammates increases coordination overhead and duplicate file reads, which degrades performance. A team of 3 agents is generally sufficient for most development tasks. You can find more details on onboarding agents to the shared index in the agent onboarding guidelines or check current pricing plans.

Additionally, you should maintain a CLAUDE.md file in the root of your repository. This file should define your project structure, coding patterns, and role boundaries. By providing this context, you prevent teammates from reading unnecessary files to understand the codebase, saving millions of tokens during parallel execution.

Finally, human oversight remains critical. While agent teams can merge changes autonomously during a session, you should inspect the final code and run local test suites before merging the changes to your main branch. Fast.io's real-time events feed and append-only audit logs help you monitor agent activity and verify that each edit complies with your development standards.