Skip to main content

Agent Teams Setup Guide

Quick setup for parallel multi-agent development with SpecWeave.

Prerequisites​

  • Claude Code CLI installed
  • SpecWeave initialized in your project (specweave init)
  • Terminal: tmux (recommended) or iTerm2 (macOS)

Step 1: Install Terminal Multiplexer​

tmux (Recommended — Cross-Platform)​

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt install tmux

# Windows (WSL)
sudo apt install tmux

iTerm2 (macOS Alternative)​

  • Install from iterm2.com
  • Enable Shell Integration: iTerm2 → Install Shell Integration
  • Enable Python API: Settings → General → Magic → Enable Python API

Step 2: Enable Agent Teams​

Add to your .claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Restart Claude Code after changing settings.

Step 3: Run Your First Team​

Quick Start with Presets​

/sw:team-build --preset full-stack "Build user authentication"

Custom Orchestration​

/sw:team-lead "Build checkout with Stripe payments, React frontend, and Node.js backend"

Step 4: Monitor Progress​

/sw:team-status          # One-time check
/sw:team-status --watch  # Auto-refresh

Step 5: Merge Results​

/sw:team-merge           # Merge all agent work

Available Presets​

PresetAgentsUse When
full-stack3 (shared → backend + frontend)Building features across stack
review3 (security + quality + docs)Code review before release
testing3 (unit + e2e + coverage)Comprehensive test generation
tdd3 (red → green → refactor)Test-driven development
migration3 (schema → backend + frontend)Database or API migrations

Terminal Navigation​

ModeHow to Switch Panes
tmuxCtrl+B then arrow keys
iTerm2Click on pane
In-processShift+Up / Shift+Down

Troubleshooting​

IssueFix
Agents not spawningVerify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set. Restart Claude Code.
tmux panes freezetmux kill-server and retry. Use in-process mode as fallback.
File conflicts between agentsCheck file ownership with --dry-run flag before launching.
Token costs too highUse smaller presets or --max-agents 2.

Further Reading​

  • Agent Teams & Swarms Guide — Architecture and concepts
  • /sw:team-lead — Custom team formation
  • /sw:team-build — Preset-based team launch