Skip to main content

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 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.
Agent Teams is an experimental feature and is disabled by default. You must opt in before using it.

​
Enabling Agent Teams

Add the following to your settings.json (user or project level): 
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
Settings file locations:
ScopePath
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
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.

​
Starting a Team

Once enabled, describe the task and team structure in natural language: 
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

SubagentsAgent Teams
CommunicationReport results back to caller onlyTeammates message each other directly
CoordinationMain agent manages all workShared task list with self-coordination
Best forFocused tasks where only the result mattersComplex work requiring discussion and collaboration
Token costLowerHigher
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.