Zum Inhalt springen
AI Learning

Architecture & Coordination

Learn

Team Lead & Teammates

Meta-Controller

A central controller agent delegates tasks to specialized worker agents and aggregates their results.

Advantages

  • Clear hierarchy
  • Easy to debug
  • Good workflow control

Disadvantages

  • Single point of failure
  • Controller bottleneck
  • Limited flexibility

Example

Claude Code with subagents: Orchestrator plans, subagents execute subtasks.

An Agent Team consists of two roles:

Team Lead -- this is your main session in Claude Code. The lead:

  • Coordinates the overall task and breaks it into subtasks
  • Spawns teammates for parallel work
  • Receives status updates and results
  • Can communicate directly with individual teammates or broadcast to all

Teammates -- these are independent Claude instances that the lead starts. Each teammate:

  • Runs as an independent Claude process with its own context
  • Has access to the same codebase (typically in its own Git worktree)
  • Can pick up tasks from the Shared Task List
  • Communicates with the lead and other teammates via a messaging system

iAnalogy: Scrum Team

The lead is like the tech lead in a Scrum team: they plan the tasks, distribute them, and keep the overview. The teammates are the developers who work independently on their tasks but can communicate with each other when needed.

Coordination Primitives

Agent Teams use three mechanisms for coordination:

1. Shared Task List

All tasks are stored as files in ~/.claude/tasks/. Each task has:

  • A title and description
  • A status: pending --> in_progress --> completed
  • Optional dependencies on other tasks
  • The assigned teammate

File Locking ensures that two teammates can't claim the same task simultaneously. When Teammate A claims a task, it is atomically marked as in_progress -- before Teammate B can see it.

2. Peer-to-Peer Messaging

Agents can communicate directly with each other:

  • message -- send a message to a specific teammate
  • broadcast -- send a message to all teammates

Messaging works via a mailbox system: Each agent has an inbox that they regularly check. Messages are not processed immediately but during the recipient's next tool-call cycle.

3. Automatic Dependency Resolution

Tasks can depend on each other. When Task B depends on Task A:

  1. Task B remains in pending status as long as Task A is not completed
  2. As soon as Task A is finished, Task B is automatically released
  3. The next available teammate can then pick up Task B

This enables natural workflows: first implement the API, then write the tests for it.

Display Modes

Agent Teams can be displayed in different modes:

ModeDescriptionSwitching
in-processAll teammates in the same terminalShift+Down to cycle through
tmuxEach teammate in its own tmux paneAutomatic in tmux session
iTerm2Each teammate in its own iTerm2 tabAutomatic in iTerm2

The in-process mode is the default. You see the lead in the main window and can scroll through teammates with Shift+Down. With tmux or iTerm2, each teammate automatically gets its own pane or tab.

Activation

You activate Agent Teams via the feature flag:

Option 1: In settings.json (recommended for permanent use)

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Option 2: As an environment variable (for one-time testing)

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude

!Experimental -- Adjust Expectations

Since Agent Teams are experimental, unexpected behavior may occur. Start with simple scenarios (2 teammates, clear task separation) and gradually increase complexity.

What happens when two teammates try to claim the same task simultaneously?

Understand

Why This Architecture?

The combination of Shared Task List and messaging solves two fundamental problems of distributed systems:

  1. Coordination without bottleneck: The lead doesn't need to monitor every step. Teammates work independently based on the task list.
  2. Flexibility in unexpected situations: If a teammate encounters a problem, they can inform the lead or another teammate via message.

The file locking system is intentionally kept simple -- it uses the filesystem instead of a database. This is robust enough for typical team sizes (2--10 teammates, up to 16) and requires no additional infrastructure.

Reflect

The architecture of Agent Teams follows proven patterns from distributed systems development: task queues, message passing, and lock-based synchronization. In the next section, we'll take a closer look at the details of task management and the messaging system.