> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mains.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Teams

> Coordinate multiple Claude Code instances working together on complex tasks

Agent Teams let you run multiple Claude Code sessions as a coordinated team inside Mains. One session acts as the **team lead** — it breaks down work, spawns teammates, and synthesizes results. Each teammate runs in its own context window and can communicate directly with other teammates.

<Note>
  Agent Teams is an experimental feature and is disabled by default. You must opt in before using it.
</Note>

## **Enabling Agent Teams**

Add the following to your `settings.json` (user or project level):

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Settings file locations:

| **Scope**        | **Path**                              |
| :--------------- | :------------------------------------ |
| User (global)    | `~/.claude/settings.json`             |
| Project (shared) | `.{your_project}/settings.json`       |
| Local (personal) | `.{your_project}/settings.local.json` |

## **When to Use Agent Teams**

Agent teams work best when multiple people — or in this case, agents — can explore a problem in parallel without blocking each other:

* **Research and review** — multiple reviewers checking security, performance, and test coverage simultaneously
* **New modules** — each teammate owns a separate, independent piece of a feature
* **Debugging** — teammates test competing hypotheses in parallel
* **Cross-layer work** — frontend, backend, and tests each handled by a different teammate

<Warning>
  Agent teams consume significantly more tokens than a single session. For sequential or tightly coupled tasks, a single session or subagents are more cost-effective.
</Warning>

## **Starting a Team**

Once enabled, describe the task and team structure in natural language:

```text theme={null}
Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
```

Claude creates the team, spawns teammates, assigns tasks, and coordinates work automatically.

## **Subagents vs Agent Teams**

|                   | **Subagents**                               | **Agent Teams**                                     |
| :---------------- | :------------------------------------------ | :-------------------------------------------------- |
| **Communication** | Report results back to caller only          | Teammates message each other directly               |
| **Coordination**  | Main agent manages all work                 | Shared task list with self-coordination             |
| **Best for**      | Focused tasks where only the result matters | Complex work requiring discussion and collaboration |
| **Token cost**    | Lower                                       | Higher                                              |

**Limitations**

* Session resume (`/resume`, `/rewind`) does not restore in-process teammates
* One team per session — clean up the current team before starting another
* Teammates cannot spawn their own teams (no nesting)
* All teammates inherit the lead’s permission mode at spawn time
* Split-pane mode is not supported in mains desktop app.