Agent Teams

Subagents are workers, you give them a task, they do it, they report back. Agent teams are peers, multiple Claude Code instances running side by side, sharing a task list, coordinating through a lead agent. One Claude instance is the lead; it assigns work to teammates, collects results, and makes decisions. The teammates run in parallel, each with its own terminal session and context window, communicating through a shared channel rather than the parent-child hierarchy of subagents.

What you'll learn

• Teams are activated with --teammate-mode, which has three variants: auto (Claude decides whether to team up), in-process (teammates share the same process), and tmux (each teammate gets its own tmux pane)
• The lead agent coordinates peers, maintains the shared task list, and decides who works on what. Teammates execute assigned tasks and report back
• Teammates communicate through a shared task list, the lead posts tasks, teammates claim them, update status, and post results. All teammates can see the list
• The TeammateIdle hook fires when a teammate finishes its current task and has nothing to do. Use it to automatically assign the next task from the queue or to signal the lead
• Agent teams are distinct from subagent delegation: teams are peer-to-peer with shared visibility; subagents are parent-to-child with isolated context

The problem

You have a feature that requires work across five areas: a database migration, an API endpoint, a frontend component, integration tests, and documentation. A single Claude Code session can do all five, sequentially. The migration takes 3 minutes, the API endpoint 5 minutes, the frontend 10, the tests 4, and the docs 2. Sequential execution: 24 minutes.

Subagent delegation improves this: spawn five General-purpose subagents in batch mode. The migration, API, and tests run in parallel (max 3 concurrent), then the frontend and docs queue up. Total: ~14 minutes.

But there's a problem: the frontend agent needs to know the API schema the API agent is building. The docs agent needs to reference the actual endpoints, not a spec. The test agent needs to test against the real migration. Subagents are isolated, they don't share context during execution. The lead has to collect results, re-synthesize, and re-delegate with updated context. That's a coordination tax that eats half the parallelism gain.

Agent teams solve this with shared visibility. All teammates see the shared task list. When the API teammate finishes, it posts the endpoint schema to the list. The frontend teammate sees it immediately and can adapt. The docs teammate references the live API. The lead agent monitors the whole board and rebalances if one teammate finishes early.

Team mode variants

Mode	How it runs	When to use it
auto	Claude decides on a per-task basis whether to spawn a team or work alone	General use, let Claude determine when parallelism helps
in-process	Teammates run as parallel contexts within the same Claude Code process	Shared memory, fast startup, good for short-lived tasks where process isolation isn't needed
tmux	Each teammate gets its own tmux pane in the terminal	Visual transparency, you can watch each teammate work in its own pane. Best for long-running teams where you want to monitor progress

Auto mode in practice

To let Claude automatically determine when a task would benefit from parallelism, launch the CLI with auto teammate mode enabled.

claude --teammate-mode auto

When you give Claude a task with clear parallelizable components, it evaluates whether splitting into a team would help. If yes, it spawns teammates. If the task is inherently sequential, it stays solo. You don't decide, Claude does.

Auto mode is the lowest-friction entry point. The trade-off is that Claude's team-spawning decisions are heuristic, it might team up for a task you'd prefer handled sequentially, or work solo on a task that would benefit from parallelism. If you find auto mode making the wrong call, switch to explicit in-process or tmux.

In-process mode

When you need fast startup and memory sharing for short tasks, use the in-process mode to run teammates within the same runtime.

claude --teammate-mode in-process

Teammates share the same process space. This means faster startup (no new terminal sessions) and shared memory access, but less isolation. If one teammate crashes, it can affect others. Use in-process for short coordination bursts where overhead matters.

Tmux mode

If you want complete visibility into what each teammate is doing, the tmux mode isolates them into separate terminal panes.

claude --teammate-mode tmux

Each teammate opens in its own tmux pane. You see every teammate's terminal in a split view. This is the most transparent mode, if a teammate gets stuck, you see the exact prompt and output. It's also the most resource-intensive because each pane is a full Claude Code process. Use tmux for long-running teams, debugging team coordination issues, or when you want to watch the team work.

The shared task list

The shared task list is the team's coordination surface. The lead agent creates it, populates it with tasks, and teammates interact with it through tool calls:

1. Lead creates the board: The lead agent breaks the goal into tasks and posts them to the shared list
2. Teammates claim tasks: A teammate sees an unclaimed task that matches its capabilities, claims it, and starts working
3. Status updates: As the teammate works, it updates the task status , in_progress, blocked, done
4. Results posted: When a teammate finishes, it posts the result to the task entry. All teammates can see it
5. Lead rebalances: If a teammate posts blocked (waiting for another teammate's output), the lead can reassign or reprioritize

The task list is not a Kanban board in the visual sense, it's a structured data object that Claude instances read and write through tool calls. But functionally, it works the same way: a shared view of who's doing what and what's waiting.

The TeammateIdle hook

When a teammate finishes a task and has nothing to do, it fires the TeammateIdle hook. You configure this hook to:

• Automatically claim the next unassigned task from the shared list
• Signal the lead agent that this teammate is available
• Run cleanup or logging before the teammate goes idle

Without this hook, an idle teammate sits waiting until the lead explicitly assigns it work. With it, the team self-balances, idle workers pull from the queue automatically.

{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "",
        "command": "echo 'Teammate idle, checking for next task'"
      }
    ]
  }
}

Build it

Step 1: Start a team session

Begin your team session by launching Claude with tmux mode enabled to monitor the workflow across multiple panes.

claude --teammate-mode tmux

You'll see tmux split into panes, one for the lead agent at the top, and empty panes for teammates below. The number of teammates defaults to 3 but is configurable.

Step 2: Give the lead agent a parallelizable task

At the lead agent's prompt:

We need to add a "user preferences" feature end-to-end. Break this into:
1. Database migration: add a user_preferences table with JSONB settings column
2. Backend API: CRUD endpoints for preferences under /api/users/:id/preferences
3. Frontend: a settings page component that calls the API
4. Integration tests: test the full flow from frontend to database
5. Documentation: update the API docs with the new endpoints

Coordinate the team. Assign tasks to teammates. The API teammate should post
its endpoint schema to the shared task list so the frontend teammate can build
against it. The test teammate should wait until the API and frontend are done.

Step 3: Watch the coordination

The lead agent creates the task list and starts assigning. You'll see:

• Teammate 1 starts the database migration (independent, runs first)
• Teammate 2 starts the API endpoints (depends on migration schema, but can stub)
• Teammate 3 starts the frontend (depends on API schema, waits for Teammate 2 to post it)
• When Teammate 1 finishes, the lead assigns it to docs or tests
• The shared task list updates as statuses change

In tmux mode, you can switch between panes with Ctrl+B then arrow keys to watch each teammate's terminal directly.

Step 4: Use TeammateIdle for auto-claiming

Configure the hook so idle teammates automatically pull from the queue:

In .claude/settings.json:

{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "",
        "command": "echo '{{AGENT_NAME}} idle, pulling next task'"
      }
    ]
  }
}

Now when Teammate 1 finishes the migration, instead of sitting idle, it checks the shared task list for unclaimed tasks and claims one automatically. The lead agent doesn't need to manually reassign.

What goes wrong

Mistake	How you notice it	The fix
Teammates work on conflicting files	Two teammates edit the same file simultaneously, one's changes overwrite the other's	The lead agent should assign file ownership: "Teammate 1 owns db/, Teammate 2 owns api/, Teammate 3 owns frontend/". If tasks genuinely need to touch the same file, sequence them, don't parallelize
A teammate goes idle and never claims new work	One pane is stuck at a prompt while others are working	Check that TeammateIdle hook is configured. Without it, idle teammates need the lead to explicitly assign tasks. Add the hook or have the lead poll for idle teammates and reassign
Lead agent becomes a bottleneck	Teammates finish tasks but wait for the lead to collect results and assign new ones before continuing	Reduce the lead's granularity. Instead of assigning one task at a time, give each teammate a batch of 2–3 tasks. The lead only intervenes when dependencies shift or a teammate reports blocked
Tmux panes become unreadable with many teammates	8 panes in a terminal window, each showing 5 lines of output	Cap teammates at 3–5 for tmux mode. If you need more parallel workers, use in-process mode or background agents instead
Team context grows faster than expected	The shared task list accumulates verbose status updates, and each teammate's context fills with other teammates' output	Teammates should post concise status updates, one-line summaries, not full logs. The lead agent should enforce a format: [TEAMMATE] [STATUS] [TASK] [ONE-LINE RESULT]

Confirm it worked

Execute this validation script to ensure your agent teams can coordinate on a multi-file generation task without conflict.

# 1. Start a team session (tmux mode for visibility)
claude --teammate-mode tmux

# 2. Give a simple parallel task:
#    "Write three independent utility functions to src/utils/:
#     - formatDate.ts (date formatting)
#     - slugify.ts (URL slug generation)
#     - debounce.ts (debounce utility)
#     Assign one to each teammate. Each teammate writes its file and reports back."

# 3. Verify:
#    - tmux splits into panes (lead + 3 teammates)
#    - Each teammate writes its assigned file
#    - All three files exist in src/utils/ after the team finishes
#    - The lead agent reports a summary of what each teammate produced

# 4. Check the files:
ls src/utils/formatDate.ts src/utils/slugify.ts src/utils/debounce.ts

# If all three files exist and the team coordinated without conflicts, agent teams are working.

Next: Background Agents , running independent parallel sessions with --agent-view.