← 19.420.2 →
1296 words No Slides

Video 20.1: Introduction to Agent Teams

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

Opening Hook

Agent Teams are a game-changer for complex projects. Instead of working alone, you can spawn multiple Claude agents that work together in parallel, each with their own context window and focus. Let me show you how this fundamentally changes what you can build with Claude Code.

Key Talking Points

What to say:

The Problem We're Solving - Most Claude Code sessions are one-to-one: you (the lead) with one Claude agent - For large projects, this becomes a bottleneck: Claude can't split focus, and your lead can't simultaneously code and review - Real teams have different specialists: an architect thinks about structure, a backend dev implements, a frontend dev builds the UI, a QA person tests - Agent Teams let you replicate that natural division of labor

The Agent Teams Architecture - One Team Lead (that's you) coordinates the effort - Multiple Teammates (each a Claude instance) work independently with their own context windows - The lead doesn't fight for attention anymore—teammates work in parallel while you orchestrate - This is fundamentally different from "subagents" or calling Claude's API multiple times; it's a coordinated, persistent team

Team Lead Role - Decides what needs doing - Spawns teammates with specific focus areas - Receives updates and manages the overall vision - Can code alongside teammates or step into "Delegate Mode" to coordinate only - Synthesizes results from different teammates - Makes final decisions on architecture and direction

Teammate Role - Focused on a specific task or domain - Runs in their own context, completely independent - Can chat with the lead and other teammates - Self-claims tasks or accepts assignments - Reports progress to the lead - No nested teams: teammates can't spawn their own teammates

Shared Task List Concept - All team members see the same task board - Stored at ~/.claude/tasks/{team-name}/ - Tasks can have dependencies: "can't start the UI until the API is designed" - Lead can assign work or let teammates self-volunteer - Prevents duplicate work and keeps everyone aligned

Why This Matters for Real Development - Parallel work on independent features happens simultaneously - Specialists can use specialized prompts and skills - Lead maintains quality control without being a bottleneck - Natural for larger codebases that require multiple skill sets

What to show on screen:

  • Terminal with Claude Code running
  • Brief structure overview: show ~/.claude/teams and ~/.claude/tasks directories (don't go deep yet)
  • A simple team being spawned (show the natural language request)
  • Multiple teammate contexts appearing as the team forms
  • The task board with several tasks in different states

Demo Plan

0:00-0:30 - Setup and Problem Statement - Start with Claude Code in a simple project context (e.g., a starter repo with a basic structure) - Talk about scaling challenges: "If I'm the only one working on this, everything goes through me" - Show terminal is ready to work

0:30-1:30 - Spawn a Simple Team - Use natural language: "Create a team with 3 teammates: one focused on the API, one on the frontend, and one on testing" - Watch teammates spawn and settle into their own context windows - Narrate what's happening: each teammate is independent, they have separate contexts - Show the task board starts populating with initial tasks - Highlight the Team Lead position (where you are) vs teammate positions

1:30-2:45 - Show the Architecture in Action - Give the team a concrete task: "Build a simple REST API endpoint and a frontend component that calls it" - Watch the API teammate start working on the endpoint while the frontend teammate independently works on the component - Show them asking the lead (you) questions via direct message - Narrate the parallel nature: "Notice how they're both working at the same time. In a single-agent session, I'd have to choose which one to focus on" - Briefly show the task board updating as teammates mark progress

2:45-3:30 - Highlight Key Differences - Pause and explain: this isn't just running Claude Code three times in different terminals - This is a coordinated team with shared context, shared task awareness, and real-time collaboration - Lead the team in a quick synthesis: "Let's review what you built" and show both the API endpoint and the frontend working together

3:30-4:00 - Lead-out - Explain that in the next videos we'll configure this properly, understand roles, and master the tools - Tease delegation mode and display options - "This is just the beginning—let's learn how to make the most of it"

Code Examples & Commands

Spawning a Basic Team

# In Claude Code, use natural language:
> Create a team with 3 teammates focused on these areas:
> - API backend development
> - React frontend
> - Unit testing

What the Directories Look Like

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

~/.claude/tasks/{team-name}/
  pending/
    task-1.json
    task-2.json
  in-progress/
  completed/

Example Team Configuration (Reference)

{
  "team_name": "example-build",
  "lead_model": "claude-opus-4-6",
  "teammates": [
    {
      "name": "api_dev",
      "model": "claude-opus-4-6",
      "role": "Backend API Development"
    },
    {
      "name": "frontend_dev",
      "model": "claude-sonnet-4-20250514",
      "role": "React Frontend"
    },
    {
      "name": "qa",
      "model": "claude-sonnet-4-20250514",
      "role": "Testing and Quality Assurance"
    }
  ]
}

Gotchas & Tips

Gotchas: - Teammates cannot spawn other teammates (no nested teams) - Only one team per session: if you try to spawn while a team is running, you'll need to clean up the first one - The Team Lead is fixed for the session: you can't transfer leadership - In-process display mode doesn't support session resumption—if you close the terminal, context is lost

Tips: - Start with 2-3 teammates for your first team to keep cognitive load manageable - Be clear about role boundaries when spawning: "one for API architecture, one for implementation" is better than three vague teammates - The shared task list is your communication hub—use it actively - Teammates respect the lead's vision: set clear direction upfront to avoid conflicting approaches

Lead-out

Agent Teams fundamentally change how you can approach complex projects. In the next video, we'll enable this feature properly and configure it for your workflow. You'll learn how to turn on the experimental flag and customize the behavior to your specific needs.

Reference URLs

  • Claude Code Official Documentation: https://www.anthropic.com/claude-code
  • Claude Agent SDK (theoretical foundation): https://sdk.anthropic.com
  • GitHub Issues on Agent Teams (experimental feedback): https://github.com/anthropics/anthropic-sdk-python/discussions

Prep Reading

  • Review the Agent SDK architecture documentation (conceptual understanding of multi-agent systems)
  • Skim through any community discussions or blog posts about AI team coordination
  • Familiarize yourself with the ~/.claude directory structure on your system
  • Think about a concrete project scenario where you'd benefit from a team (multi-service app, full-stack project, etc.)

Notes for Daniel

The demo here is more conceptual than technical. You're setting expectations and showing the "wow" moment. Don't get bogged down in details about hooks or task JSON structure—that comes in later videos. Keep energy high; this is about unlocking new possibilities. The audience will be thinking "I could use this for my project" by the end. Pace yourself: 4 minutes will feel short if you talk too fast through the spawning, so let the team initialization breathe a bit so viewers can see it happen.

If the terminal is slow to spawn teammates, talk through what's happening in the background rather than filling silence. "Claude's initializing three independent context windows now—this takes a moment but happens in the background." Risk of demo failure: network latency during team spawn. Have a backup pre-recorded clip of team spawn ready, or a dry-run team already created.