# How to Orchestrate Claude Code Agent Teams

Orchestrating parallel developer agents requires coordination to prevent file conflicts. This guide explains how to enable Claude Code agent teams, configure split panes in tmux, and connect sessions to shared workspaces.

Source: https://fast.io/resources/claude-code-agent-teams-setup/
Last reviewed: 2026-08-23

## Why Single-Instance Coding Agents Cause Write Collisions

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 Enable the Agent Teams Experimental Feature

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:

```bash
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:

```json
{
  "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.

## How to Manage Teammates in Terminal or tmux Panes

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:

```json
{
  "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.

## How Teammates Coordinate Without Overwriting Code

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.

## How to Connect Parallel Agent Sessions to Fast.io Workspaces

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](/storage-for-agents/).

For structured document processing, developers can use [Metadata Views](/product/document-data-extraction/) 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:

```json
{
  "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](/storage-for-agents/). 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.

## Best Steps for Optimizing Token Budgets

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](https://fast.io/llms.txt) or check current [pricing plans](/pricing/).

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.

## Frequently asked questions

### How to enable agent teams in Claude Code?

To enable agent teams, set the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` environment variable to `1` in your terminal or shell profile. You can also make this setting persistent by adding the variable to the `env` block in your global `~/.claude/settings.json` file.

### What is the difference between Claude Code subagents and agent teams?

Standard subagents are sequential workers that report directly to a parent session. In contrast, agent teams consist of independent Claude Code sessions that run in parallel, coordinate tasks via a local task list, and communicate peer-to-peer using a mailbox system.

### How do you configure the teammate display mode in Claude Code?

You can configure the display mode using the `teammateMode` setting in your `~/.claude/settings.json` file. Set it to 'in-process' to cycle through active teammates in your main terminal window, or 'tmux' to display teammates in separate terminal panes.

## About Fast.io

Fast.io provides shared workspaces where people and AI agents work on the same files, with built-in semantic search and citation-backed chat over what they hold. Agents reach it through a remote MCP server at https://mcp.fast.io/mcp, a REST API at https://api.fast.io/current/, and a command line client published on npm as @vividengine/fastio-cli.