Video 19.4: Setting Up Your Environment

Course: Claude Code - Parallel Agent Development (Course 4) Section: 19 - Multi-Agent Fundamentals Video: 19.4 of 4 Duration: 4-5 minutes Presenter: Daniel Treasure

Opening Hook

"Ready to actually run multiple agents? There's some setup involved, but it's not complicated. We'll enable the experimental agent teams feature, install tmux or configure iTerm2 for split-pane visualization, and walk through the basic configuration. By the end of this video, you'll have a working multi-agent environment on your machine."

Key Talking Points

Step 1: Enable Agent Teams Feature

What to say: - Agent teams are experimental, so you need to opt in - There are two ways: environment variable or settings file - Either method works; choose whichever fits your workflow - The environment variable is quick for one-off testing - The settings file is persistent across sessions

What to show on screen: - Open a terminal and show both methods - Show before/after: settings without the flag, then with it

Option A: Environment Variable - export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 - Then start Claude Code: claude code - This is temporary (only for that terminal session)

Option B: Settings File - Edit ~/.claude/settings.json - Add the experimental flag - Persistent across all sessions

Step 2: Choose Your Display Mode

What to say: - Once agent teams are enabled, you need to decide how to visualize multiple agents - Three options: in-process (default), tmux split panes, or iTerm2 - In-process: agents run within Claude Code, navigate with Shift+Up/Down - tmux: each agent in its own terminal pane (great for seeing all agents simultaneously) - iTerm2: uses iTerm2's native split panes (macOS only) - Your choice depends on your OS and preference

What to show on screen: - Show the three visualization modes side-by-side (screenshots or demo) - Highlight how each mode looks different but functions the same - Emphasize tmux as the universal option (works on Linux, macOS, Windows with WSL)

Step 3: Install and Configure tmux (Recommended)

What to say: - tmux is the most flexible and widely-used option - It's available on Linux, macOS, and Windows (via WSL) - Installation is straightforward via package manager - Basic configuration is optional but useful for multi-agent development

What to show on screen: - Show installation commands for different OSes - Show basic tmux configuration - Demonstrate creating split panes manually, then explain how Claude Code automates this

Step 4: Configure iTerm2 (macOS Only)

What to say: - If you're on macOS and already use iTerm2, it's a great option - iTerm2 has a Python scripting API that Claude Code can use - Setup is more involved but gives native integration - You'll need the iTerm2 Python library installed

What to show on screen: - Show iTerm2 setup instructions - Demonstrate the Python script that enables Claude Code integration - Show a split-pane example with iTerm2

Step 5: Team Configuration Basics

What to say: - Once display mode is chosen, configure your team - Team configuration lives at ~/.claude/teams/{team-name}/config.json - You can create a team by starting Claude Code with a team name - Key settings: team name, list of teammates, delegation mode, display mode

What to show on screen: - Show a sample team configuration file - Point out each key section: name, lead, teammates, display_mode, delegate_mode - Explain what each setting does

Step 6: Creating Your First Team

What to say: - You can create a team in two ways: via CLI flag or interactive setup - CLI flag: claude code --team my-compiler-team --teammates 4 - Interactive: claude code, then use /team command to configure - Either way, you're essentially creating a config file and spawning agents - The lead agent (first one) coordinates; teammates work independently

What to show on screen: - Demonstrate the CLI approach - Show the resulting team configuration file - Show the task list at ~/.claude/tasks/my-compiler-team/

Delegate Mode (Optional but Powerful)

What to say: - Delegate mode changes how the lead behaves - Default (off): lead can write code and coordinate - Delegate mode (on): lead only coordinates, doesn't write code - Useful for truly distributed work: lead plans, delegates, reviews; teammates execute - Toggle with Shift+Tab during a session

What to show on screen: - Show the delegate mode toggle - Explain the UI change when delegate mode is on - Show how leads can approve/reject plans without coding

Demo Plan

0:00–0:45 - Enable Agent Teams 1. Open terminal, show settings.json without the experimental flag 2. Edit settings.json to add experimental.agent_teams = true 3. Show the file saved 4. Alternative: Show the environment variable approach 5. Say: "Either way works. I prefer settings file for persistence."

0:45–2:00 - Install and Configure tmux 1. Show tmux installation: brew install tmux (macOS) or apt install tmux (Linux) 2. Show a basic tmux config file (~/.tmux.conf) 3. Demonstrate creating split panes manually: tmux new-session -d -s demo -x 200 -y 50 then tmux split-window -h 4. Show the resulting side-by-side panes 5. Say: "Claude Code will do this automatically when you enable tmux as the display mode."

2:00–3:15 - Create Your First Team Configuration 1. Open terminal, create ~/.claude/teams/demo-team/ directory 2. Create a config.json file with basic settings: json { "name": "demo-team", "lead": "lead-agent", "teammates": ["agent-1", "agent-2"], "display_mode": "tmux", "delegate_mode": false } 3. Show the file in an editor 4. Explain each field 5. Save the file

3:15–4:15 - Start a Team Session 1. Open terminal 2. Start Claude Code with the team: claude code --team demo-team 3. Show the team initializing (might be quick since it's a demo) 4. Demonstrate Ctrl+T to toggle task list view 5. Show Shift+Up/Down navigation between agents (or tmux pane switching) 6. Say: "You're now in a multi-agent session. The lead coordinates, teammates work independently."

4:15–4:45 - Quick Walkthrough of Team Commands 1. Show /team command to view team info 2. Show Shift+Tab to toggle delegate mode 3. Show Ctrl+T to toggle task list 4. List task files: ls ~/.claude/tasks/demo-team/ 5. Say: "These are the core commands and files you'll work with. Next section dives into actual multi-agent workflows."

Code Examples & Commands

Enable Agent Teams in Settings

# Edit ~/.claude/settings.json
# Add or modify:
{
  "experimental": {
    "agent_teams": true
  },
  "agent_teams": {
    "display_mode": "tmux",
    "delegate_mode": false,
    "auto_sync_tasks": true
  }
}

Enable Agent Teams via Environment Variable

# Temporary (for this session only)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude code

# Or set permanently in ~/.bashrc or ~/.zshrc
echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
source ~/.zshrc

Install tmux

# macOS (using Homebrew)
brew install tmux

# Ubuntu/Debian
sudo apt update
sudo apt install tmux

# Fedora/RHEL
sudo dnf install tmux

# Verify installation
tmux -V

Basic tmux Configuration

# Create ~/.tmux.conf
cat > ~/.tmux.conf << 'EOF'
# Set prefix to Ctrl+Space
unbind C-b
set -g prefix C-Space
bind C-Space send-prefix

# Enable mouse support
set -g mouse on

# Split panes
bind v split-window -h
bind s split-window -v

# Navigate panes
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# Default terminal
set -g default-terminal "screen-256color"

# Status bar
set -g status-bg black
set -g status-fg white
EOF

# Reload configuration
tmux source-file ~/.tmux.conf

Create Team Configuration Manually

# Create team directory
mkdir -p ~/.claude/teams/my-team

# Create config.json
cat > ~/.claude/teams/my-team/config.json << 'EOF'
{
  "name": "my-team",
  "lead": "lead-agent",
  "teammates": ["frontend-agent", "backend-agent", "db-agent"],
  "display_mode": "tmux",
  "delegate_mode": false,
  "max_parallel_agents": 3,
  "task_sync_interval": 5,
  "auto_approve_plans": false
}
EOF

Start a Multi-Agent Team Session

# Start with CLI flags
claude code --team my-team --teammates 3 --display-mode tmux

# Or let Claude Code create the team interactively
claude code
# Then use /team command to configure

# View team info
claude code --team my-team --info

Team Commands During Session

# Available commands (type in Claude Code session):

/team                      # Show team info
/team status               # Show teammate statuses
/team tasks                # List shared tasks
/team task <id> approve    # Approve a task plan
/team task <id> reject     # Reject a task plan

# Keyboard shortcuts:
Ctrl+T                     # Toggle task list view
Shift+Up/Down              # Navigate between teammates (in-process mode)
Shift+Tab                  # Toggle delegate mode
Ctrl+B                     # Run subagent in background (within teammate session)

iTerm2 Setup (macOS Only)

# Install iTerm2 Python library
pip3 install iterm2

# Enable iTerm2 integration in settings.json
cat >> ~/.claude/settings.json << 'EOF'
{
  "agent_teams": {
    "display_mode": "iterm2",
    "iterm2_window_size": "200x50"
  }
}
EOF

# Verify iTerm2 version supports Python scripting
/Applications/iTerm.app/Contents/MacOS/iTerm2 --version

Task List File Structure

# After starting a team session, task list is at:
ls ~/.claude/tasks/{team-name}/

# Contents:
# task-001.json - Task 1
# task-002.json - Task 2
# assigned/
#   task-001-frontend-agent.json - Task 1 assigned to frontend-agent
#   task-001-status.json - Status updates

# View a task
cat ~/.claude/tasks/my-team/task-001.json

Gotchas & Tips

Gotcha: Agent Teams Requires Recent Claude Code Version

The experimental flag only works on recent versions
Make sure you've updated Claude Code: claude code --version
If it doesn't recognize the flag, update first

Tip: Start Simple

Don't create a 10-agent team for your first go
Start with 2-3 agents, learn how coordination works
Scale up as you get comfortable

Gotcha: tmux Learning Curve

If you're new to tmux, there's a small learning curve
Take 5 minutes to learn basic commands: pane navigation, closing panes, etc.
Good investment for future multi-pane work

Tip: Keep the Task List Open

Ctrl+T to toggle task list view is your friend
Seeing what each agent is working on is crucial for coordination
Make this a habit

Gotcha: Display Mode Affects Session Persistence

In-process mode: sessions can't be resumed if you close Claude Code
tmux mode: sessions persist in tmux, you can reattach
If you need persistence, use tmux or iTerm2

Tip: Use Delegate Mode for True Distribution

Shift+Tab toggles delegate mode
If you want the lead to only coordinate (not code), enable it
Great for a project manager coordinating multiple developers

Gotcha: Teammates Start Read-Only

When a teammate is first spawned, they work in read-only mode on the main codebase
They can write to their own task files and logs
Only after lead approval can they write to the main codebase
This prevents accidental overwrites

Tip: Monitor Token Usage

Multi-agent consumes tokens fast (multiple context windows)
Check your API dashboard regularly
Set up spending alerts on your Anthropic account

Tip: Use Git for Coordination

Even with agent teams, use version control
Agent commits should be atomic and well-documented
Makes debugging and reverting easier

Gotcha: No Nested Teams

You can't have a team within a team
One team per session
Plan your agent count upfront

Lead-Out

"You've got everything set up. Agent teams enabled, tmux running (or iTerm2 if you're on macOS), team configuration saved. You're now equipped to start building with multiple agents. The next section goes deep into actual multi-agent workflows and patterns: how to structure work, divide tasks, handle synchronization, and avoid common pitfalls. You've got the theory and the setup; now let's build something real."

Reference URLs

Prep Reading

Install tmux on your system (if not already installed)
Read tmux basics: pane creation, navigation, closing
Review iTerm2 scripting if you're planning to use that mode
Understand git basics (will be important for multi-agent coordination)
Familiarize yourself with ~/.claude/ directory structure

Notes for Daniel

This is a hands-on video. Viewers will be following along, trying to replicate your steps. Go slow, show each file edit, and explain what you're doing. Clarity > speed.

The demo should feel natural: you're setting up your development environment, just like you would for any new project. Normalize this setup as "just part of the process."

For tmux, if you're comfortable with it, do a quick demo of pane navigation and closing. This helps viewers who've never used tmux understand how it works. But don't spend too much time on tmux basics; that's not the focus.

For iTerm2 setup, if you're on macOS, do it live. If not, you can reference it or show screenshots. The key point is "there are options depending on your platform."

The team configuration file is the real payoff: show it, explain each field, save it. This is what enables everything else.

Time: Hook (30s), enable feature (1:00), tmux (1:15), team config (1:15), start session (1:00), commands walkthrough (30s). Allocate extra time to demo if needed.

Tone: You're a practical guide. The viewer should feel confident that they can do this on their own machine. No magic, just straightforward setup steps.

Final thought: Emphasize that this setup is a one-time thing. Once it's done, they can use claude code --team my-team from any project and multi-agent development is off to the races.

Quick Reference