Lesson 18: Agent Teams & Teammates

Learning Objectives

After completing this lesson, you will be able to:

Understand what agent teams are and when to use them
Set up split-pane collaboration (tmux, WezTerm, iTerm2)
Create and manage agent teams
Use spawnTeam functionality
Enable teammate communication patterns
Troubleshoot agent team issues (fixed in 2.1.33)

Prerequisites

Completed Lessons 1-17 - Core operations and multi-agent concepts
Familiarity with tmux, WezTerm, or iTerm2 - For split-pane workflows
Multi-agent experience - Lesson 14 recommended
Appropriate plan - Agent teams require specific subscription tiers

Estimated Time: 40 minutes

What Are Agent Teams?

Agent Teams allow multiple Claude Code instances to work together in split-pane terminals, collaborating in real-time on the same task.

Concept: Teammates Working Side-by-Side

Think of Agent Teams like developers pair programming:

┌─────────────────┬─────────────────┐
│  Teammate 1     │  Teammate 2     │
│  (Backend Dev)  │  (Frontend Dev) │
│                 │                 │
│  Working on     │  Working on     │
│  API endpoints  │  UI components  │
└─────────────────┴─────────────────┘
         │                   │
         └─────────┬─────────┘
                   │
            Communication
              Channel

Key benefits:

Visual collaboration - See teammates work in real-time
Specialized roles - Each teammate focuses on one area
Direct communication - Teammates send messages to each other
Parallel execution - Multiple tasks run simultaneously
Shared context - All teammates access the same project

When to Use Agent Teams

Best use cases:

Full-stack development - Backend + frontend working together
Microservices - Multiple services being updated simultaneously
Code review - One teammate reviews, another implements
Testing + development - One writes tests, one implements features
Documentation + code - One documents, one codes
Multi-language projects - Different teammates for different languages

When NOT to use:

Simple single-file changes
Quick questions or lookups
Linear tasks that can't be parallelized

Setting Up Split-Pane Collaboration

Agent Teams work with split-pane terminals. As of 2.1.33, Claude Code supports:

Supported Terminals

tmux (Most common)
- Works on Linux, macOS, Windows (WSL)
- Powerful terminal multiplexer
- Requires configuration
WezTerm (NEW in 2.1.33!)
- Modern GPU-accelerated terminal
- Cross-platform (Windows, macOS, Linux)
- Fixed teammate sessions in 2.1.33
iTerm2 (macOS only)
- Feature-rich macOS terminal
- Native split-pane support
- Fixed teammate sessions in 2.1.33

Configuring tmux for Agent Teams

Step 1: Install tmux

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Fedora
sudo dnf install tmux

Step 2: Configure tmux

Create or edit ~/.tmux.conf:

# Enable mouse control
set -g mouse on

# Use C-a as prefix (optional, more comfortable than C-b)
unbind C-b
set -g prefix C-a
bind C-a send-prefix

# Split panes using | and -
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# Switch panes using Alt-arrow without prefix
bind -n M-Left select-pane -L
bind -n M-Right select-pane -R
bind -n M-Up select-pane -U
bind -n M-Down select-pane -D

# Easy pane cycling
bind -r C-a select-pane -t :.+

Step 3: Start tmux

tmux new-session -s claude-team

Configuring WezTerm (NEW in 2.1.33!)

Step 1: Install WezTerm

Download from: https://wezfurlong.org/wezterm/

Step 2: Configure WezTerm

Edit ~/.wezterm.lua:

local wezterm = require('wezterm')
local config = {}

config.keys = {
  -- Split horizontally
  {
    key = '|',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.SplitHorizontal {
      domain = 'CurrentPaneDomain',
    },
  },
  -- Split vertically
  {
    key = '-',
    mods = 'CTRL|SHIFT',
    action = wezterm.action.SplitVertical {
      domain = 'CurrentPaneDomain',
    },
  },
}

return config

Verifying Terminal Support

You> Check if my terminal supports agent teams

Claude: I'll check your terminal configuration.

[Bash agent checks environment]

Claude: Your terminal is configured with:
- Terminal: tmux 3.3a
- Split support: Yes
- Teammate mode: Available

Agent teams will work correctly in your current session.

Creating Agent Teams

Method 1: Using `spawnTeam` Tool

The spawnTeam tool creates a team of teammates that work in split panes.

Basic team creation:

You> Create a team of 2 teammates to help refactor this codebase

Claude: I'll spawn a team of 2 teammates to help with refactoring.

[Spawning teammates...]

tmux: Splitting into 3 panes (1 main + 2 teammates)

Team Configuration:
┌─────────────┬─────────────┬─────────────┐
│  Main (you) │ Teammate 1  │ Teammate 2  │
│  Coord      │ Backend     │ Frontend    │
└─────────────┴─────────────┴─────────────┘

Teammate 1: Focused on backend API refactoring
Teammate 2: Focused on frontend component updates

All teammates can communicate and coordinate.

Method 2: Settings Configuration

Configure teams in settings.json:

{
  "agentTeams": {
    "fullstack": {
      "name": "Full Stack Team",
      "teammates": [
        {
          "name": "backend",
          "agentType": "general-purpose",
          "model": "claude-sonnet-4-5",
          "systemPrompt": "You are a backend developer. Focus on API design, database operations, and server-side logic. Use TypeScript and Express."
        },
        {
          "name": "frontend",
          "agentType": "general-purpose",
          "model": "claude-sonnet-4-5",
          "systemPrompt": "You are a frontend developer. Focus on UI components, state management, and user experience. Use React and TypeScript."
        }
      ]
    }
  }
}

Using configured teams:

You> Spawn the fullstack team

Claude: I'll spawn the fullstack team.

[Loads team configuration from settings]

Team: Full Stack Team
- Backend teammate (claude-sonnet-4-5)
- Frontend teammate (claude-sonnet-4-5)

Setting up split-pane environment...

TeammateMode Setting

Configure how teammates are displayed in settings.json:

{
  "teammateMode": "tmux"
}

Options:

"tmux" - Use tmux split panes (Linux, macOS, WSL)
"iterm2" - Use iTerm2 split panes (macOS only)
"wezterm" - Use WezTerm split panes (cross-platform)
"in-process" - No split panes, teammates run invisibly

Teammate Communication

Team members can communicate using the SendMessage tool.

Communication Patterns

1. Main Agent → Teammate

You (Main): Tell the backend teammate to implement the user auth endpoint

Claude: I'll send a message to the backend teammate.

[Sends message via SendMessage tool]

Teammate (Backend): I'll implement the user auth endpoint.
[Backend teammate starts working on auth endpoint...]

2. Teammate → Main Agent

Teammate (Backend): I've completed the auth endpoint. Frontend teammate, please integrate it.

[Sends message via SendMessage]

Claude (Main): Backend has completed the auth endpoint.
Forwarding request to frontend teammate...

Teammate (Frontend): I'll integrate the auth endpoint now.

3. Teammate ↔ Teammate

Teammate (Backend): Frontend, I need the user ID format for the API response.

Teammate (Frontend): We need UUID format: { "id": "uuid", "email": "..." }

Teammate (Backend): Got it, updating the response format now.

Monitoring Teammate Activity

Watch what teammates are doing in their split panes:

┌───────────────────┬───────────────────┬───────────────────┐
│ Main: Coordinating│ Backend: Working  │ Frontend: Idle    │
│                   │                   │                   │
│ Claude: Backend,  │ Teammate: Reading │ Teammate: Waiting │
│ update the API    │ src/api/auth.ts   │ for backend...    │
│                   │                   │                   │
│ [Context shows    │ [Context shows    │ [Context shows    │
│  all teammates]   │  auth files]      │  component files] │
└───────────────────┴───────────────────┴───────────────────┘

Practical Example: Full-Stack Feature

Let's build a complete feature using an agent team.

Scenario: User Authentication Feature

Task: Implement user registration and login with backend API and frontend UI.

Step 1: Create the Team

You> Create a fullstack team to implement user authentication

Claude: I'll spawn a 2-teammate fullstack team.

[Spawns teammates in split panes]

Team Structure:
┌────────────┬──────────────┬──────────────┐
│ You (Main) │ Backend      │ Frontend     │
│            │ Teammate     │ Teammate     │
└────────────┴──────────────┴──────────────┘

Step 2: Assign Tasks

You> Backend teammate, implement the registration and login API endpoints.
Frontend teammate, create the login and registration forms.

Claude: I'll send these tasks to both teammates.

[Sending messages...]

Step 3: Watch Collaboration

Backend Pane:

Teammate (Backend): I'll implement the auth API endpoints.

[Creating src/api/auth.ts]
- POST /api/auth/register
- POST /api/auth/login
- GET /api/auth/me

[Implementing validation and JWT tokens]

Frontend Pane:

Teammate (Frontend): I'll create the auth UI components.

[Creating components/LoginForm.tsx]
[Creating components/RegisterForm.tsx]
[Implementing form validation]

Step 4: Coordinate Integration

Teammate (Backend): Frontend, the API is ready at:
- POST /api/auth/register
- POST /api/auth/login

Request body: { "email": string, "password": string }
Response: { "token": string, "user": {...} }

Teammate (Frontend): Got it! Integrating with the API now.

[Frontend updates to call backend endpoints]

Step 5: Main Agent Coordinates

You: Both teammates, please test the complete flow

[Both teammates run tests]

Backend: All API tests passing ✓
Frontend: UI integration working ✓

Claude: The authentication feature is complete!

Troubleshooting (2.1.33 Fixes)

Common Issues and Solutions

Issue 1: "Agent Teams not available on your current plan"

This warning appears when your subscription doesn't include agent teams.

Solution:

Agent teams require specific plan tiers
Check your plan at /usage or /status
Upgrade if needed

Issue 2: Teammates not sending/receiving messages (FIXED in 2.1.33!)

Previous versions had issues with tmux teammate communication.

Fixed in 2.1.33:

Teammate sessions in tmux now correctly send and receive messages
WezTerm support added for split-pane teammates
iTerm2 teammate messaging fixed

Issue 3: Teammates running in-process instead of split panes

Cause: Terminal doesn't support split panes or teammateMode not set.

Solution:

Check terminal support: /doctor

Set teammateMode in settings:

{
  "teammateMode": "tmux"  // or "wezterm", "iterm2"
}

Restart Claude Code

Issue 4: iTerm2 silently falls back to in-process

Cause: iTerm2 CLI not detected when inside tmux.

Solution:

Don't run tmux inside tmux
Launch Claude Code in iTerm2 directly (not inside tmux)
Or use tmux as your primary terminal

Best Practices

1. Role Specialization

Give each teammate a clear, focused role:

{
  "agentTeams": {
    "microservices": {
      "teammates": [
        {
          "name": "auth-service",
          "systemPrompt": "You work on authentication services only. Focus on security, JWT handling, and user management."
        },
        {
          "name": "data-service",
          "systemPrompt": "You work on data services only. Focus on database operations, queries, and data validation."
        },
        {
          "name": "api-gateway",
          "systemPrompt": "You work on the API gateway only. Focus on routing, rate limiting, and request orchestration."
        }
      ]
    }
  }
}

2. Communication Protocols

Establish clear communication patterns:

Backend → Frontend: "API Ready" pattern
Backend completes endpoint
Sends message with endpoint documentation
Frontend acknowledges and integrates

Frontend → Backend: "API Request" pattern
Frontend needs new endpoint
Sends message with requirements
Backend acknowledges and implements

Use shared context files:

<!-- .claude/team-context.md -->
# Team Context

## API Endpoints
- POST /api/users - Create user
- GET /api/users/:id - Get user
- PUT /api/users/:id - Update user

## Data Models
User: { id, email, name, createdAt, updatedAt }

## Team Responsibilities
- Backend: API implementation, database
- Frontend: UI components, API integration

All teammates can reference this file.

4. Testing Together

Have teammates test each other's work:

Backend: I've implemented the user endpoints. Can you test them?
Frontend: Testing now...
[Frontend runs integration tests]

Frontend: All tests passing! Good work.
Backend: Thanks! Ready for the next task.

✅ Check Your Understanding

Which terminals support agent teams?
- Only tmux
- tmux, WezTerm, and iTerm2
- All terminals
- Only iTerm2
What tool is used to create agent teams?
- spawnAgent
- spawnTeam
- createTeam
- teamUp
True or False: Teammates can communicate directly with each other.
- True
- False
What was fixed in 2.1.33 regarding agent teams?
- Added tmux support
- Fixed teammate messaging in tmux
- Added spawnTeam tool
- Fixed WezTerm rendering
How many teammates can you have in a team?
- Only 1
- Maximum 2
- As many as your terminal can display
- Maximum 4

Answers: 1-b, 2-b, 3-True, 4-b, 5-c

Summary

In this lesson, you learned:

Agent Teams - Multiple Claude instances working in split panes
Split-pane terminals - tmux, WezTerm (NEW!), iTerm2 support
spawnTeam - Create and manage teams of teammates
Teammate communication - SendMessage for coordination
2.1.33 fixes - Reliable teammate messaging

Next Steps

In Lesson 19: Forked Context & Advanced Skills, you'll learn:

Forked sub-agent context
Skill hot-reload (automatic!)
Language settings
Advanced skill frontmatter

Learning Objectives​

Prerequisites​

What Are Agent Teams?​

Concept: Teammates Working Side-by-Side​

When to Use Agent Teams​

Setting Up Split-Pane Collaboration​

Supported Terminals​

Configuring tmux for Agent Teams​

Configuring WezTerm (NEW in 2.1.33!)​

Verifying Terminal Support​

Creating Agent Teams​

Method 1: Using spawnTeam Tool​

Method 2: Settings Configuration​

TeammateMode Setting​

Teammate Communication​

Communication Patterns​

Monitoring Teammate Activity​

Practical Example: Full-Stack Feature​

Scenario: User Authentication Feature​

Troubleshooting (2.1.33 Fixes)​

Common Issues and Solutions​

Best Practices​

1. Role Specialization​

2. Communication Protocols​

3. Context Sharing​

4. Testing Together​

✅ Check Your Understanding​

Summary​

Next Steps​

Further Reading​

Learning Objectives

Prerequisites

What Are Agent Teams?

Concept: Teammates Working Side-by-Side

When to Use Agent Teams

Setting Up Split-Pane Collaboration

Supported Terminals

Configuring tmux for Agent Teams

Configuring WezTerm (NEW in 2.1.33!)

Verifying Terminal Support

Creating Agent Teams

Method 1: Using `spawnTeam` Tool

Method 2: Settings Configuration

TeammateMode Setting

Teammate Communication

Communication Patterns

Monitoring Teammate Activity

Practical Example: Full-Stack Feature

Scenario: User Authentication Feature

Troubleshooting (2.1.33 Fixes)

Common Issues and Solutions

Best Practices

1. Role Specialization

2. Communication Protocols

3. Context Sharing

4. Testing Together

✅ Check Your Understanding

Summary

Next Steps

Further Reading