Guide

Agent Teams — When to Use What

5 modes for 5 situations. Pick the right tool for the job.

Decision framework

Match the mode to the task

Single file fix

Regular Claude Code session

No agents needed. Open the file, describe the bug, let Claude fix it. Done in 30 seconds.

3 independent tasks, no dependencies

Agent View

Dispatch all 3 in parallel, check results when done. Each agent works in isolation on its own file set.

Repeatable workflow (review, test, docs)

Subagents with config

Consistent every time. Define the workflow once, run it on every PR or commit. Same quality bar without manual oversight.

Multi-file feature with dependencies

Agent Teams

Lead coordinates, teammates collaborate. Backend agent writes the API, frontend agent consumes it, test agent validates both.

Overnight backlog drain

Headless mode

Set a --max-budget-usd cap and walk away. Claude works through the queue autonomously until the budget runs out.

The difference

Solo mode vs. agent teams

Before (solo)

✗One task at a time, sequentially
✗You write, then review, then test, then commit
✗4-part feature takes a full day
✗Context bloats as you hold everything in one session

After (agent team)

✓4 agents working in parallel
✓Backend, frontend, tests, and review simultaneously
✓Same feature ships in 2 hours
✓Clean focused context per agent — you review and merge

Configuration

Setup in 60 seconds

Environment variables

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929"
export CLAUDE_CODE_DEFAULT_EFFORT=high
export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1

Permission config

{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Write(src/**)",
      "Write(tests/**)"
    ],
    "deny": [
      "Read(**/.env*)",
      "Bash(rm -rf *)",
      "Bash(git push *)"
    ],
    "defaultMode": "acceptEdits"
  }
}

Headless mode

claude -p "build the auth system" --max-budget-usd 15.00

Pre-configured

Squad templates

Build Squad

Architect2 CodersTester

New features, migrations, refactors

Quality Squad

ReviewerSecurityPerformance

Pre-merge validation, audit, load testing

Content Squad

WriterDesignerSEO

Docs, blog posts, marketing pages

Research Squad

ResearcherScraperAnalyst

Competitive analysis, trend reports, data collection

All 4 squad templates pre-built in AI Brain Pro

Agent team configs, permission sets, squad templates, headless mode budgets, and the full orchestration layer. Install in 30 seconds.

Get AI Brain Pro — $97

Match the mode to the task

Single file fix

Regular Claude Code session

No agents needed. Open the file, describe the bug, let Claude fix it. Done in 30 seconds.

3 independent tasks, no dependencies

Agent View

Dispatch all 3 in parallel, check results when done. Each agent works in isolation on its own file set.

Repeatable workflow (review, test, docs)

Subagents with config

Consistent every time. Define the workflow once, run it on every PR or commit. Same quality bar without manual oversight.

Multi-file feature with dependencies

Agent Teams

Lead coordinates, teammates collaborate. Backend agent writes the API, frontend agent consumes it, test agent validates both.

Overnight backlog drain

Headless mode

Set a --max-budget-usd cap and walk away. Claude works through the queue autonomously until the budget runs out.

Solo mode vs. agent teams

Before (solo)

✗One task at a time, sequentially
✗You write, then review, then test, then commit
✗4-part feature takes a full day
✗Context bloats as you hold everything in one session

After (agent team)

✓4 agents working in parallel
✓Backend, frontend, tests, and review simultaneously
✓Same feature ships in 2 hours
✓Clean focused context per agent — you review and merge

Setup in 60 seconds

Environment variables

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-5-20250929" export CLAUDE_CODE_DEFAULT_EFFORT=high export CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1

Permission config

{ "permissions": { "allow": [ "Read", "Glob", "Grep", "Edit", "Write(src/**)", "Write(tests/**)" ], "deny": [ "Read(**/.env*)", "Bash(rm -rf *)", "Bash(git push *)" ], "defaultMode": "acceptEdits" } }

Headless mode

claude -p "build the auth system" --max-budget-usd 15.00

Squad templates

Build Squad

Architect2 CodersTester

New features, migrations, refactors

Quality Squad

ReviewerSecurityPerformance

Pre-merge validation, audit, load testing

Content Squad

WriterDesignerSEO

Docs, blog posts, marketing pages

Research Squad

ResearcherScraperAnalyst

Competitive analysis, trend reports, data collection