Video 20.7: Display Modes and Terminal Setup

Course: Claude Code - Parallel Agent Development Section: S20 - Agent Teams Video Length: 4 minutes Presenter: Daniel Treasure

Opening Hook

Navigating between teammates with Shift+Up/Down works, but it's clunky. Display modes let you see your entire team at once—in split panes or separate windows. Let's explore the options and pick the best one for your workflow.

Key Talking Points

What to say:

The Display Mode Problem - In-process mode requires manual navigation (Shift+Up/Down) - You see one teammate at a time - You can't visually monitor multiple teammates working in parallel - Works for small teams but gets tedious fast

Three Display Mode Options

In-Process Mode (Default)
All teammates run in the same terminal window
You navigate with Shift+Up/Down
Pros: Works everywhere, no extra setup, single terminal
Cons: Can only see one teammate at a time, manual switching required
Best for: Small teams (2-3), simple sequential work, minimal terminal setup
Config: "teammate_mode": "in-process" or --teammate-mode in-process
tmux Split Panes
Each teammate gets their own pane in a tmux session
All teammates visible simultaneously
You can see everyone working in real-time
Click into a pane to interact with that teammate
Pros: Full visibility, elegant, works on most Unix/Linux/Mac systems
Cons: Requires tmux to be installed, needs terminal to be in tmux session, learning curve
Best for: Larger teams (3-5+), parallel work visualization, development workflows
Config: "teammate_mode": "tmux" or --teammate-mode tmux
iTerm2 Split Panes
Mac-specific, uses iTerm2's native pane splitting
Similar to tmux but integrated into iTerm2
Requires iTerm2 CLI and Python API access
Pros: Native to Mac terminal, clean integration
Cons: Mac-only, requires iTerm2 installed, setup complexity
Best for: Mac developers who love iTerm2
Config: "teammate_mode": "iterm2" or --teammate-mode iterm2

"Auto" Mode - Intelligently chooses the best display mode for your environment - If you're in a tmux session: uses tmux split panes - If not in tmux: falls back to in-process mode - No explicit configuration needed (or set "teammate_mode": "auto") - Best for: Most developers; "just works"

Setting the Display Mode

Via settings.json:

{
  "teammate_mode": "tmux"
}

Via CLI flag:

claude --teammate-mode tmux

Terminal Compatibility - Supported: Linux terminals (bash, zsh), macOS (bash, zsh, iTerm2), WSL - Not supported: Windows Terminal, VS Code integrated terminal, Ghostty - Tip: If your terminal isn't supported, use in-process mode

tmux Setup - You need tmux installed (brew install tmux on Mac, apt-get install tmux on Linux) - Claude Code will create a new tmux session automatically when you spawn a team - Each teammate gets a split pane - You (the lead) get your own pane - You can resize panes, click between them, etc. - No manual tmux commands needed; Claude Code handles it

Managing tmux Panes - Click into a pane to focus it - Type to send messages to that teammate - Mouse scrolling works within panes - You can resize panes by dragging borders (terminal-dependent) - All panes share the same team session

Switching Between Modes - You can change modes between sessions - Set it in config or use CLI flag - Restart Claude Code to apply new mode - In-process mode doesn't lose state; switching is clean

When to Use Each Mode

Use In-Process: - Small teams (1-2 teammates) - Quick prototyping - You're comfortable with context switching - You don't have tmux set up and don't want to - Simple sequential work (one task at a time)

Use tmux: - Medium-to-large teams (3-5+ teammates) - Parallel work (multiple teammates working simultaneously) - You want to monitor progress visually - You're comfortable with tmux or want to learn - Longer development sessions where visibility matters

Use iTerm2: - You're on a Mac - You already use and love iTerm2 - You want native integration rather than tmux

Use "Auto": - You don't care; let Claude Code choose - Safe default for most workflows - Scales with your setup

What to show on screen:

Terminal with Claude Code running in in-process mode
Demonstrate Shift+Up/Down navigation briefly
Explain the limitation: can only see one teammate at a time
Switch to tmux mode
Show Claude Code spawning a team in tmux
Display the split pane layout with all teammates visible
Show clicking between panes and interacting with different teammates
Compare the two modes visually
Optionally show iTerm2 if on a Mac system
Show the config/CLI changes to switch modes

Demo Plan

0:00-0:45 - Current Setup: In-Process Mode - Have Claude Code running with a team in in-process mode - Show teammate A working on something - Press Shift+Down to switch to teammate B - Narrate: "In-process mode, I navigate between teammates. It works, but I can only see one at a time" - Show the overhead of switching contexts - Explain: "For a larger team, this gets tedious"

0:45-1:30 - Introduce tmux Split Panes - Exit the current in-process team (cleanup) - Show the settings.json or command-line change: "teammate_mode": "tmux" - Restart Claude Code or specify the mode - Spawn a team: "Create a team with 3 teammates" - Watch the tmux session initialize with split panes - Narrate: "Now each teammate has their own pane. I can see everyone working at once"

1:30-2:30 - Demonstrate tmux Layout - Point out the pane layout: lead pane, teammate 1, teammate 2, teammate 3 (typical 2x2 grid) - Show each pane with its teammate's context and active work - Click into different panes to show interaction - Send a message from one pane to switch focus - Show how tmux pane borders are visible and draggable - Narrate: "This is what parallel work looks like. Everyone visible, everyone working" - Let the demo breathe—viewers should see the power of seeing multiple agents at once

2:30-3:15 - Show the Configuration Options - Go back and show the settings.json entry - Demonstrate the CLI flag: claude --teammate-mode tmux - Briefly mention the "auto" option - Explain: "Auto is the safe default. It picks tmux if you're in a tmux session, otherwise in-process" - Show compatibility limitations: "Windows Terminal and VS Code integrated terminal aren't supported yet"

3:15-3:45 - Compare Modes Visually - If time permits, switch back to in-process mode to show the contrast - Narrate: "Both modes work. In-process is simpler; tmux is more powerful for large teams" - Give the decision tree: small team? in-process. Larger team? tmux. - Optional: mention iTerm2 if on Mac

3:45-4:00 - Lead-out - Confirm that display mode is a choice, not a requirement - Next video is about plan approval and quality gates - Tease: "Now that you can see your team, let's talk about ensuring quality"

Code Examples & Commands

Set Display Mode in settings.json

{
  "api_key": "sk-...",
  "teammate_mode": "tmux"
}

Set Display Mode via CLI

# In-process mode
claude --teammate-mode in-process

# tmux mode
claude --teammate-mode tmux

# Auto mode (recommended)
claude --teammate-mode auto

# Or just the shorthand for auto (default)
claude

Check Your Terminal Compatibility

# Is tmux installed?
which tmux

# Install tmux if needed:
# macOS:
brew install tmux

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

# Linux (Fedora):
sudo dnf install tmux

Spawn a Team in tmux Mode

# Assuming you have "teammate_mode": "tmux" in settings.json
claude

# Then spawn:
> Create a team with 3 teammates

Start a Fresh tmux Session (Manual, if needed)

# If you want tmux running before Claude Code:
tmux new-session -s claude-team

# Then run Claude Code within that session
claude

Configuration Example (Full)

{
  "api_key": "sk-...",
  "default_model": "claude-opus-4-6",
  "experimental_agent_teams": true,
  "teammate_mode": "auto",
  "auto_save": true
}

Gotchas & Tips

Gotchas: - tmux mode requires tmux to be installed; if it's not, you'll get an error - If you're not in a tmux session and use teammate_mode: tmux, Claude Code will try to create one (might behave unexpectedly) - Using teammate_mode: auto is safer than forcing tmux; it adapts to your environment - On Windows, tmux may not be available by default (WSL + tmux can work) - VS Code integrated terminal doesn't work with tmux; you need a native terminal - If you have panes that are too small to see content, they're hard to resize - Switching from tmux back to in-process mode loses the split view, but context is preserved

Tips: - Start with "teammate_mode": "auto" for maximum compatibility - If you're new to tmux, use in-process mode first; learn tmux later - tmux panes are resizable; if you have 4 teammates, a 2x2 grid is cleaner than a single column - For Mac users, "auto" will prefer tmux over iTerm2 integration; if you prefer iTerm2, set it explicitly - Large team size (6+ teammates) might need smaller panes; consider the screen real estate - Use multiple monitors to spread out panes if working with a large team - In tmux mode, you can detach and reattach the session without losing state (advanced feature) - Scrollback in tmux panes uses tmux keybindings (default: Prefix+[), not terminal scroll

Lead-out

You now have full visibility into your team's work with the display mode of your choice. The last piece of the puzzle is quality control: how do you ensure that teammates deliver work that meets your standards? In the next and final video, we'll explore plan approval and quality gates—powerful tools for keeping your team on track.

Reference URLs

tmux Documentation: https://github.com/tmux/tmux/wiki
iTerm2 Official Site: https://iterm2.com/
Claude Code Display Modes: https://www.anthropic.com/claude-code/docs/agent-teams/display-modes
Terminal Emulator Comparison: https://wiki.archlinux.org/title/List_of_applications/System_utilities

Prep Reading

Install tmux if you plan to use it (and understand basic tmux pane creation)
Review your terminal emulator's capabilities; ensure it's compatible
Understand the tradeoff between simplicity (in-process) and visibility (tmux)
Consider your team size and workflow: would parallel visibility help you?

Notes for Daniel

Display modes are a visual topic; make sure the demo is clear and the terminal is well-lit (larger font, good contrast). The jump from navigating between teammates to seeing them all at once should feel liberating—that's the "aha!" moment. Don't get bogged down in tmux mechanics; keep the focus on what Claude Code does for you, not how tmux works. The comparison between modes is important; show the limitation of in-process (one at a time) and the power of tmux (all visible) side-by-side if possible. If you're not on a Mac with iTerm2 set up, mention it briefly but don't demo it; keep focus on the main two modes. End with the message: "Pick the mode that fits your team and workflow."

Risk: tmux might not be installed or terminal compatibility issues might arise. Have a backup pre-recorded clip of tmux split panes, or be prepared to fall back to a textual explanation with screenshots.

Quick Reference