Architecture Reference

Understanding how agent teams work internally.

Fresh 🌱

System Overview

Component Details

1. Team Lead

Role: Orchestrator and coordinator

Capabilities:

• Spawn teammates
• Manage task list
• Synthesize results
• Direct communication with teammates
• File editing and tool execution (unless in delegate mode)

Constraints:

• One team at a time
• Cannot be replaced/promoted to teammate
• In delegate mode: coordination-only

Lifecycle:

• Created when user starts Claude Code
• Creates team (if requested)
• Spawns teammates
• Coordinates work
• Initiates cleanup

2. Teammates

Role: Independent workers on assigned tasks

Capabilities:

• Work on assigned tasks
• Communicate with other teammates
• Update shared task list
• Read project context (CLAUDE.md, MCP servers)

Constraints:

• Cannot spawn other teammates
• Cannot run cleanup
• Cannot create new teams
• Own context window only

Lifecycle:

• Spawned by lead
• Load project context
• Receive spawn prompt
• Work independently
• Can be shut down gracefully or forced

3. Shared Task List

Storage: ~/.claude/tasks/[team-name]/

Structure:

Each task is a separate file with JSON:
{
  "id": 1,
  "title": "Implement authentication",
  "description": "...",
  "status": "in_progress",  // pending, in_progress, completed
  "owner": "Teammate 1",
  "created": "2026-02-12T14:00:00Z",
  "updated": "2026-02-12T14:15:00Z",
  "dependsOn": [2, 3],      // Task IDs this depends on
  "blocks": [4, 5]          // Task IDs waiting on this
}

Features:

• File locking prevents race conditions
• Automatic dependency resolution
• Status tracking (pending → in_progress → completed)
• Owner assignment
• Blocking relationships

4. Mailbox System

Purpose: Message delivery between agents

Behavior:

• Asynchronous message queue
• Automatic message delivery
• No polling required
• Teammates notified of new messages
• Lead receives all messages automatically

Message Types:

• Direct messages (1:1)
• Broadcast messages (1:many)
• System notifications
• Status updates

Example Flow:

Lead → "Tell Teammate 1: focus on security"
  → Stored in mailbox
  → Teammate 1 notified
  → Teammate 1 reads message
  → Teammate 1 adjusts work
  → Complete

5. Team Configuration

File: ~/.claude/teams/[team-name]/config.json

Contents:

{
  "teamName": "auth-review",
  "created": "2026-02-12T14:00:00Z",
  "leadId": "lead-uuid",
  "members": [
    {
      "name": "Security Reviewer",
      "agentId": "agent-123",
      "agentType": "teammate",
      "spawned": "2026-02-12T14:01:00Z",
      "status": "active"
    },
    {
      "name": "Performance Specialist",
      "agentId": "agent-456",
      "agentType": "teammate",
      "spawned": "2026-02-12T14:01:00Z",
      "status": "active"
    }
  ],
  "settings": {
    "teamMode": "in-process",
    "permissions": "default"
  }
}

Teammate Discovery:

• Teammates can read this file
• They know who else is on team
• They can coordinate through knowledge of team composition

Data Flow

Creating a Team

User → "Create agent team"
  ↓
Lead analyzes request
  ↓
Lead decides team composition
  ↓
For each teammate:
  - Generate spawn configuration
  - Create agent instance
  - Load project context
  - Send spawn prompt
  - Wait for startup
  ↓
Create shared task list
Create team config file
  ↓
Team ready

Teammate Working on Task

Teammate picks up task from list
  ↓
Teammate reads task details
  ↓
Teammate updates status: "in_progress"
  ↓
Teammate works on implementation
  ↓
Teammate may message other teammates
  ↓
Teammate finishes work
  ↓
Teammate updates task status: "completed"
  ↓
System unblocks dependent tasks
  ↓
Next teammate can now claim unblocked task

Lead Synthesizing Results

Lead requests: "Compile findings"
  ↓
Lead reads all completed tasks
  ↓
Lead collects teammate messages/results
  ↓
Lead synthesizes into coherent summary
  ↓
Lead saves to document
  ↓
Ready for output/sharing

Context Management

Project Context (Automatic)

Each teammate loads:

• CLAUDE.md - Project instructions
• MCP Servers - Tools and integrations
• Skills - Custom prompts
• Spawn Prompt - Role-specific instructions

Context Isolation

• Lead's conversation history NOT shared
• Each teammate has independent context
• No context bleeding between teammates
• Shared task list is the coordination mechanism

Memory Efficiency

• Each teammate is independent Claude instance
• Token usage scales with number of teammates
• Can't pass large conversation histories
• Better for focused, well-scoped work

Permission Model

Permission Inheritance

1. Startup: All teammates inherit lead's permissions
2. Runtime: Permissions can be changed per teammate
3. Spawn: Cannot set per-teammate permissions at creation
4. Flag: --dangerously-skip-permissions affects all agents

Permission Types

• File operations - Read/write/delete
• Command execution - Run tools and CLI
• Tool usage - Access to specific tools
• Network access - External API calls

Display Modes

In-Process Mode

Architecture:

Single terminal window
  ├─ Lead output
  ├─ Teammate 1 output (when selected)
  ├─ Teammate 2 output (when selected)
  └─ Teammate 3 output (when selected)

Navigation: Shift+Up/Down cycles
Storage: Single process

Advantages:

• Works anywhere
• Lower resource usage
• Simple architecture

Split Panes Mode

Architecture:

tmux Session
├─ Window 1: Lead
├─ Window 2: Teammate 1
├─ Window 3: Teammate 2
└─ Window 4: Teammate 3

All visible simultaneously
Navigation: Click or tmux keys
Storage: Multiple tmux panes

Requirements:

• tmux or iTerm2 (via it2 CLI)
• Python API (iTerm2)

File Organization

~/.claude/ Directory Structure

~/.claude/
├── settings.json          # Global settings
├── teams/
│   └── auth-review/
│       └── config.json    # Team configuration
├── tasks/
│   └── auth-review/
│       ├── task-1.json    # Individual tasks
│       ├── task-2.json
│       └── task-3.json
└── logs/
    └── team-sessions/     # Session transcripts

Token Usage

Cost Per Agent

Each teammate = separate Claude instance:

• Lead: 1 context window
• 3 teammates: 4 context windows total
• 5 teammates: 6 context windows total

Scaling

• Single agent: 1x token cost
• 3-agent team: 3-4x token cost
• 5-agent team: 5-7x token cost

When worthwhile:

• 3x token cost ÷ 2-3x speedup = 1.5x net cost for 3x faster
• Breakeven when speedup > token cost multiplier

Synchronization

File Locking

Task list uses file locks to prevent:

• Race conditions when claiming tasks
• Concurrent modifications
• Data corruption

Message Delivery

Mailbox ensures:

• No message loss
• Order preservation
• Automatic retries
• Timeout handling

Status Consistency

• Each agent updates own status atomically
• Changes visible to all immediately
• No eventual consistency delays
• Synchronous updates

Limitations & Constraints

Current Limitations

Limitation	Impact	Workaround
No session resumption	Can't /resume with teammates	Clean up and create new team
One team per lead	Can't manage multiple teams	Sequential team creation
No nested teams	Teammates can't spawn teams	Only lead can spawn
Lead is fixed	Can't rotate leadership	Plan team lifecycle upfront
Split panes needs tmux	Not available in VS Code	Use in-process mode
Task status can lag	Teammates don't mark complete	Manual status update if stuck

Best Practices for Architecture

Minimize Context Size

• Keep spawn prompts concise
• Don't include entire conversation history
• Use CLAUDE.md for project context
• Reference files by path, not content

Design Task Boundaries

• Independent tasks parallelize better
• Shared files create conflicts
• Clear ownership per teammate
• Explicit interfaces between tasks

Plan for Synchronization Points

• Identify where integration happens
• Set up explicit check-ins
• Use task dependencies
• Plan synthesis timing

Resource Efficiency

• Use Haiku for simple, fast tasks
• Use Sonnet for balanced workloads
• Use Opus for complex reasoning
• Monitor overall token usage

See Also

• SOP-002: Create Your First Team
• Delegate Mode Workflow
• Commands Reference
• Troubleshooting