Video 19.2: Multi-Agent Architecture Overview

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

Opening Hook

"There's no single way to run multiple agents in parallel. You've got three fundamentally different patterns: agent teams with their own context windows, lightweight subagents within one session, and manual git worktrees. Each has different tradeoffs in speed, cost, and complexity. Picking the right one is the difference between a smooth workflow and a coordination nightmare."

Key Talking Points

The Three Patterns Overview

What to say: - Before diving into code, let's understand the architectural landscape - Three primary patterns exist, each designed for different scenarios - None is universally "best"—the right choice depends on your task, your team, and your budget - Think of it like choosing between microservices, monolith, and serverless: different tools for different jobs

What to show on screen: - A visual title screen or diagram with three boxes labeled: "Agent Teams," "Subagents," "Git Worktrees" - Add icons or visual metaphors (e.g., Agent Teams = connected nodes, Subagents = tree structure, Git Worktrees = parallel branches)

Pattern 1: Agent Teams

What to say: - Agent teams are the newest and most native approach in Claude Code - One team lead agent coordinates the work - Each teammate gets its own context window, runs independently - They share a task list at ~/.claude/tasks/{team-name}/ - The lead can approve or reject teammate plans before execution - There are multiple ways to view them: in-process (default, Shift+Up/Down to navigate), tmux split panes, or iTerm2 - Shift+Tab toggles "delegate mode" where the lead only coordinates without writing code

What to show on screen: - Show the Claude Code CLI/UI with agent teams enabled - Highlight the task list view (Ctrl+T toggle) - Show navigation between teammates using Shift+Up and Shift+Down - If possible, show a tmux split-pane setup with multiple agents visible simultaneously - Point out the delegate mode toggle

Communication Model: - Direct peer-to-peer: teammates can see each other's progress via shared task list - The lead is the decision-maker: plans go through lead approval - Trade-off: most coordination overhead, but also most control and visibility

Pattern 2: Subagents

What to say: - Subagents are lightweight agents that run within a single session - You spawn a subagent using the /agents command - The main agent maintains the primary context window - Subagents inherit permissions and tools from the main agent - They're great for parallel subtasks that don't need heavy communication - Subagents report results back to the main agent, but don't communicate directly with each other - Built-in subagents include Explore (read-only, good for research), Plan (read-only, good for planning), General-Purpose, and Bash - You can also define custom subagents via AGENT.md files or the /agents command

What to show on screen: - Open Claude Code session, show the /agents command - Demonstrate spawning multiple subagents (e.g., /agents spawn explore for research, /agents spawn backend-dev for coding) - Show how subagents report back via the main agent's context - Highlight the built-in subagents available

Communication Model: - Tree structure: subagents report to main agent only - Main agent doesn't share context with subagents initially (they work in isolation) - Subagents see the main agent's context when they report back - Trade-off: less coordination overhead, but also less visibility between parallel workers

Pattern 3: Git Worktrees

What to say: - This is the manual, low-tech approach: use git worktrees to create isolated branches - Each worktree is a separate directory with its own working tree but shared git history - You can run a Claude Code session in each worktree independently - True isolation: each agent sees a different filesystem state - No built-in coordination—you merge changes manually when ready - Community tools exist to help: agentree, ccswarm, Crystal, parallel-cc, clash (conflict detection) - Best for when you want maximum independence and don't need real-time coordination

What to show on screen: - Terminal window showing git worktree commands - Demonstrate: git worktree list to show active worktrees - Show directory structure with multiple worktrees - Open separate terminal windows running Claude Code in each worktree (or point to them) - Show git merging when ready to integrate

Communication Model: - Manual via git: each agent has a completely separate working directory - No shared state except git history - Integration happens via git merge or manual conflict resolution - Trade-off: maximum independence but also maximum manual work

Comparison Table

What to say: - Let's compare these three across key dimensions - Context windows: teams have separate contexts (best for large tasks), subagents share one context (token-efficient), worktrees have separate contexts but no coordination overhead - Communication: teams have the most, subagents report to main only, worktrees are manual git - Coordination overhead: teams high, subagents medium, worktrees low (but manual) - Cost: teams highest (separate context windows), subagents medium, worktrees medium - Best for: teams for complex parallel work, subagents for isolated subtasks, worktrees for simple feature branches

What to show on screen: - Display a comparison table with rows: Context Windows, Communication, Coordination, Cost, Setup Complexity, Best For - Color-code or highlight key differences - Here's the reference table:

Feature	Agent Teams	Subagents	Git Worktrees
Context Windows	Separate per agent	Shared main	Separate
Communication	Shared task list, peer-to-peer	Report to main only	Manual (git merge)
Coordination Overhead	High	Medium	Low
Token Cost	Highest (N agents × context)	Medium	Medium
Setup Complexity	Enable flag + CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1	/agents command	Manual git + claude
Best For	Complex parallel work, strong coordination	Isolated parallel subtasks	Simple feature branches, maximum independence
Visibility	Excellent (shared task list)	Good (main agent orchestrates)	Manual (git history)
Real-Time Coordination	Yes	Limited	No

Demo Plan

0:00–0:45 - Agent Teams Setup & UI 1. Start Claude Code with agent teams enabled (show in settings.json or env var) 2. Show the team configuration file at ~/.claude/teams/{team-name}/config.json 3. Demonstrate Ctrl+T to toggle task list view 4. Show Shift+Up/Down navigation between teammates 5. Highlight a teammate's plan, show how the lead approves or rejects

0:45–2:00 - Subagents Demonstration 1. In a single Claude Code session, type /agents to see available agents 2. Show the built-in options: Explore, Plan, General-Purpose, Bash 3. Spawn a subagent with /agents spawn explore to research a topic 4. Show how the subagent runs independently and reports back 5. If time, spawn a second subagent simultaneously (Ctrl+B for background) 6. Return to main agent and show results from both subagents

2:00–3:30 - Git Worktrees Walkthrough 1. Open terminal, show git worktree list for an existing project 2. Demonstrate creating a new worktree: git worktree add ../feature-branch-name branch-name 3. Show the directory structure with multiple worktrees 4. Open two terminal windows side-by-side, each in a different worktree 5. Show how you could run claude code in each independently 6. Briefly show merging: git merge feature-branch-name

3:30–4:45 - Pattern Comparison & Guidance 1. Pull up the comparison table on screen 2. Walk through each row, explaining the tradeoffs 3. End with a simple decision: "Parallel, tightly-coordinated work? Agent Teams. Quick parallel subtasks? Subagents. Simple feature isolation? Git Worktrees." 4. Say: "Next video, we'll dive into the decision framework: how do you actually choose?"

Code Examples & Commands

Agent Teams Configuration

# Enable agent teams in Claude Code settings
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Or add to ~/.claude/settings.json:
{
  "experimental": {
    "agent_teams": true
  }
}

Agent Teams File Locations

# View team configuration
cat ~/.claude/teams/{team-name}/config.json

# View shared task list
ls ~/.claude/tasks/{team-name}/

# Example team config structure:
{
  "name": "compiler-team",
  "lead": "main-agent",
  "teammates": ["lexer-agent", "parser-agent", "typechecker-agent"],
  "display_mode": "tmux",
  "delegate_mode": false
}

Subagents Commands

# List available subagents
/agents

# Spawn a subagent
/agents spawn explore

# Spawn with custom agent
/agents spawn backend-dev

# Spawn in background (Ctrl+B)
/agents spawn research-task  # Ctrl+B to background

# Define custom subagent via AGENT.md
# Place in .claude/agents/my-agent/AGENT.md or ~/claude/agents/my-agent/AGENT.md

Example AGENT.md for Custom Subagent

# Custom Test Agent

role: Runs automated tests and reports results
capabilities: bash, file_read, file_write
tools_allowed: [bash, read, write]
constraints: read-only on production files

Git Worktrees Commands

# List active worktrees
git worktree list

# Create a new worktree
git worktree add ../feature-parallel-agents feature-parallel-agents

# Run Claude Code in a worktree
cd ../feature-parallel-agents
claude code  # This starts a new Claude Code session in this worktree

# View worktree status
git worktree list --porcelain

# Merge changes back
git checkout main
git merge feature-parallel-agents

# Remove a worktree
git worktree remove ../feature-parallel-agents

Viewing Multiple Worktrees in Split Panes

# Terminal 1: main branch
cd my-project
claude code

# Terminal 2: feature branch (in tmux split pane or separate terminal)
cd ../feature-parallel-agents
claude code

# Now both agents are running in parallel, each in their own context

Gotchas & Tips

Gotcha: Agent Teams Require Opt-In

The experimental flag must be set: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Without it, you get a single-agent session
Double-check your settings before starting

Tip: Delegate Mode Is Powerful

Shift+Tab toggles delegate mode: the lead can only coordinate, not write code
Useful for truly distributed work
But if the lead needs to code, toggle it off

Gotcha: No Session Resumption with In-Process Teammates

If you use in-process display mode (default), sessions can't be resumed
Use tmux or iTerm2 for persistent sessions
This is a known limitation; plan accordingly

Tip: Subagents Work Great for Research + Coding

Spawn an Explore subagent to research a problem while you code the solution
Run them in background (Ctrl+B) so they don't block you
Report results come back to main agent

Gotcha: Git Worktrees Need Manual Coordination

You're responsible for avoiding conflicts and ensuring non-overlapping work
If two agents edit the same file, you'll have merge conflicts
This is why you need clear module boundaries

Tip: Community Tools Can Help with Worktrees

agentree: orchestration for worktree-based multi-agent workflows
ccswarm: parallelization framework for Claude Code
clash: conflict detection and resolution for parallel agents
Explore these if you're doing heavy worktree-based work

Tip: Mix and Match

You don't have to choose just one pattern
Use subagents within an agent team for lightweight tasks
Use worktrees for feature isolation, then subagents within each feature
The patterns are composable

Lead-Out

"So you've got three patterns to choose from, each with different tradeoffs. The question becomes: which one fits your specific problem? That's what video 19.3 is all about. We'll walk through a decision framework, show you real examples, and help you figure out when to use each one. Plus, we'll talk about cost—because token consumption matters, and you want to make sure you're not burning money on unnecessary parallelization."

Reference URLs

Prep Reading

Review agent teams configuration and UI thoroughly
Practice spawning subagents in a test session
Create and manage a git worktree workflow locally
Read recent discussions in Claude Code community about pattern preferences
Understand the token cost implications of each approach

Notes for Daniel

This video is a mental model builder. The viewer should finish with a clear understanding of each pattern's shape and tradeoffs, not necessarily ready to implement (that's next video). Use visuals heavily: show the UI, the commands, the comparison table. Make it concrete.

When explaining communication models, use analogies: Agent Teams are like a weekly standup with a project manager. Subagents are like asking specialists to solve specific problems and report back. Worktrees are like handing off to another team with occasional sync-ups.

The demo should flow: quick teams overview, then subagents in action (faster to demo), then worktrees (also fast). End on the comparison table so it's the last thing viewers see.

Time: Hook (30s), talking points (2:00), demos (1:45), lead-out (30s). You have flex time; use it to clarify confusing points.

Tone: You're a tour guide, not a salesman. Don't push one pattern over another—they're all useful. The job is to help viewers understand the landscape.

Quick Reference