Skip to main content
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):
Settings file locations:

​
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:
Claude creates the team, spawns teammates, assigns tasks, and coordinates work automatically.

​
Subagents vs Agent Teams

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.