Claude Code Agent Teams

Appearance

SOP-003: Configure Display Modes ​

ID: SOP-003 | Version: 1.0 | Status: Current | Date: 2026-02-12

Fresh 🌱

Choose how agent teammates are displayed in your terminal - in-process (single terminal) or split panes (multiple views).

Overview ​

Agent teams support two display modes. Pick the one that matches your workflow and terminal capabilities.

Display Modes Comparison ​

Mode Descriptions ​

In-Process Mode (Default) ​

All teammates run in your main terminal. Switch between them using keyboard shortcuts.

Pros:

  • Works in any terminal (VS Code, Windows Terminal, etc.)
  • No extra software needed
  • Familiar single-terminal workflow

Cons:

  • Can only see one teammate at a time
  • More context switching
  • Need to cycle through to monitor all

Navigation:

  • Shift+Up/Down: Cycle through teammates
  • Enter: Enter teammate's session
  • Escape: Stop current turn
  • Ctrl+T: Toggle task list

Split Panes Mode ​

Each teammate gets its own terminal pane. See all output simultaneously.

Pros:

  • Monitor all teammates at once
  • Click into any pane to interact
  • Better for parallel observation
  • Desktop view of all activity

Cons:

  • Requires tmux or iTerm2
  • More complex setup
  • Higher CPU usage
  • Not available in VS Code terminal

When to use:

  • Large teams (4+ teammates)
  • Complex coordination work
  • Monitoring is critical
  • You have tmux/iTerm2 available

Configuration ​

Set Default Mode ​

Edit ~/.claude/settings.json:

json
{
  "teammateMode": "in-process"
}

Options:

  • "in-process": In-process mode (default)
  • "tmux": Split panes using tmux
  • "auto": Split panes if already in tmux, otherwise in-process

Override for Single Session ​

bash
# Force in-process mode for this session
claude --teammate-mode in-process

# Force split panes mode for this session
claude --teammate-mode tmux

Installing Split Panes Support ​

macOS/Linux: Install tmux ​

bash
# macOS (using Homebrew)
brew install tmux

# Linux (Ubuntu/Debian)
sudo apt-get install tmux

# Linux (Fedora/RHEL)
sudo dnf install tmux

# Verify installation
tmux -V

iTerm2: Install it2 CLI ​

bash
# Install via pip
pip install it2

# Or via homebrew
brew install it2

# Verify
it2 --version

Then enable Python API:

  1. Open iTerm2
  2. Go to Settings → General
  3. Find "Magic" section
  4. Check "Enable Python API"
  5. Restart iTerm2

Windows: Use WSL with tmux ​

If using Windows Terminal or PowerShell:

bash
# Install WSL if needed
wsl --install

# Inside WSL
sudo apt-get install tmux

# Start Claude Code inside WSL terminal
claude --teammate-mode tmux

Step-by-Step: Switch Display Modes ​

Scenario 1: Use In-Process by Default ​

  1. Edit settings.json:

    bash
    # macOS/Linux
open ~/.claude/settings.json

# Windows
notepad $env:USERPROFILE\.claude\settings.json

  2. Add or update:

    json
    {
  "teammateMode": "in-process"
}

  3. Save and restart Claude Code

  4. Create a team:

    Create an agent team with 2 teammates

  5. Navigate with Shift+Up/Down

Scenario 2: Use Split Panes by Default ​

  1. Install tmux (see "Installing Split Panes Support" above)

  2. Edit settings.json:

    json
    {
  "teammateMode": "tmux"
}

  3. Create a team:

    Create an agent team with 3 teammates

  4. Each teammate appears in separate pane

Scenario 3: Auto-Detect Mode ​

json
{
  "teammateMode": "auto"
}

Claude Code will:

  • Use split panes if you're inside a tmux session
  • Use in-process otherwise

Verification Checklist ​

✓ In-Process Mode Working

  • Start Claude with: claude --teammate-mode in-process
  • Create team
  • Shift+Up/Down successfully cycles between teammates
  • Task list appears with Ctrl+T

✓ Split Panes Mode Working

  • Start Claude with: claude --teammate-mode tmux
  • Create team
  • Each teammate appears in separate pane
  • Click into pane to interact
  • Can see all output simultaneously

✓ Correct Mode by Default

  • Check ~/.claude/settings.json
  • Restart Claude without flags
  • Verify correct mode is used

Troubleshooting ​

Q: "tmux not found" error A:

  1. Install tmux: brew install tmux (macOS) or apt-get install tmux (Linux)
  2. Verify: which tmux
  3. Restart Claude Code

Q: Split panes not working in VS Code terminal A:

  1. Split panes require tmux or iTerm2
  2. VS Code terminal doesn't support tmux
  3. Use in-process mode or open native terminal

Q: Need to switch modes mid-session? A:

  1. You cannot change modes without restarting
  2. Clean up current team: Clean up the team
  3. Restart Claude Code with new flag: claude --teammate-mode in-process
  4. Create new team

Q: Panes are too small to read A:

  1. Resize your terminal window
  2. tmux will adjust pane sizes automatically
  3. Or exit and start with larger window

Q: iTerm2 panes appearing in background A:

  1. Verify Python API enabled in iTerm2 settings
  2. Restart iTerm2 after enabling
  3. Try again

Performance Tips ​

In-Process Mode ​

  • Best for 2-3 teammates
  • Lower resource usage
  • Good for laptops/limited systems

Split Panes Mode ​

  • Best for 4+ teammates
  • More terminal space needed
  • Higher resolution monitor recommended
  • Better for monitoring complex work

See Also ​