Stop Going Solo: How to Use Claude’s Agent Teams to Let AI Do the Work

Agent Teams Overview

Agent Teams is an experimental feature of Claude Code that lets multiple Claude instances work together as a coordinated team. Each member runs in its own context window, can communicate directly with other members, and shares a task list that the Lead coordinates.

Core Features

Parallel work : multiple Claude instances process different tasks simultaneously.

Team collaboration : a Lead coordinates work, teammates execute assigned tasks, and members can exchange messages directly.

Autonomous task management : the Lead can assign tasks or members can claim them, task dependencies are supported, and task status is automatically synchronized.

Comparison with Subagents

Context : each Agent Teams member has an independent context; Subagents run inside the main session.

Communication : Agent Teams members communicate directly; Subagents only report to the main agent.

Coordination : Agent Teams share a task list and self‑coordinate; Subagents are managed entirely by the main agent.

Typical use case : Agent Teams for complex work that requires discussion and collaboration; Subagents for focused tasks that only need a final result.

Token cost : Agent Teams incurs higher token usage because each member is a separate instance; Subagents have lower cost as results are merged into the main context.

When to Use Which

Use Subagents when you need a fast, focused worker that can report results quickly.

Use Agent Teams when team members must share findings, challenge each other, and collaborate autonomously.

Scenarios to Avoid Agent Teams

Agent Teams adds coordination overhead and consumes more tokens. Avoid it for:

Strictly sequential tasks with hard dependencies (e.g., design DB schema → implement API → write tests).

Editing the same file, which leads to merge conflicts.

Highly coupled work that requires frequent synchronization.

Simple, direct tasks where a single agent would be faster.

Environment Preparation

Prerequisites

Claude Code

macOS, Linux, or Windows (via WSL)

Enable Agent Teams

Agent Teams is disabled by default. Enable it via settings.json or an environment variable.

Method 1 – settings.json

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

Method 2 – Environment Variable export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 Reload your shell afterwards (e.g., source ~/.zshrc or source ~/.bashrc).

Configure Multi‑Pane Display (tmux)

Agent Teams supports two display modes:

In‑process mode : all members run inside a single terminal.

Split‑pane mode : each member gets its own tmux pane.

Run claude --teammate-mode in-process to force in‑process mode.

In split‑pane mode you can switch panes with shift + ↑/↓ and view each member’s session.

Enable Mouse Support in tmux

macOS shortcuts conflict with tmux’s default Ctrl‑B prefix. Enable mouse mode to click panes, scroll, and resize: set -g mouse on Or change the prefix to Ctrl‑A:

set -g prefix C-a
unbind C-b
bind C-a send-prefix

iTerm2 Extra Configuration (macOS Recommended)

Install the Python API: pip install iterm2 Enable “Applications in terminal may access clipboard” and grant Full Disk Access in System Settings.

Building Your First Agent Team

Prompt Claude Code to create a team, for example:

创建一个3人团队的AgentTeams.前端开发，后端开发，产品经理兼职UI设计，然后一个测试，先创建好团队，我再给你说需求。

The Lead creates separate sessions for each member and a main session to coordinate.

Lead Approval (Plan Mode)

For high‑risk tasks, members must submit a read‑only plan that the Lead approves before execution.

Delegation Mode

If the Lead does not want to write code, enable delegation mode so the Lead only coordinates while teammates handle implementation.

Cleaning Up a Team

Clean up the team

Running the cleanup removes shared resources; ensure all members are stopped before cleaning.

Agent Teams Structure

Team‑Lead : main Claude Code session that creates the team and coordinates work.

Teammates : independent Claude Code instances that execute assigned tasks.

Task list : shared list of work items that teammates claim and complete.

Mailbox : message‑passing system for inter‑agent communication.

Configuration files are stored locally under ~/.claude/teams/{team‑name}/config.json and ~/.claude/tasks/{team‑name}/.

Use Cases

Parallel Code Review

Assign separate reviewers for security, performance, and test coverage so each focuses on a different aspect without overlap.

Competing‑Hypothesis Investigation

Generate multiple agents, each tasked with a different hypothesis, and force them to challenge each other, reducing anchoring bias.

Practical Pitfalls and Solutions

Pitfall 1 – tmux Pane Switching Fails

Problem: Ctrl‑B + arrows do not switch panes on macOS.

Cause: macOS shortcuts conflict with tmux.

Solution: Enable mouse mode ( set -g mouse on) or remap the prefix to Ctrl‑A.

Pitfall 2 – iTerm2 Clipboard Permission

Grant clipboard access in iTerm2 Settings → General → Selection → “Applications in terminal may access clipboard”.

Pitfall 3 – Stale tmux Sessions

List sessions with tmux ls and kill them with tmux kill-session -t <name> or tmux kill-server.

Advanced Tips

Plan Approval Mode : Require a read‑only plan before any changes.

Quality Gates : Use hooks to enforce rules.

Task Size Guidance : Ideal tasks are a single function, test file, or code review; avoid tasks that are too tiny or too large.

Avoid File Conflicts : Assign different files/modules to each teammate, use separate Git branches, and set file locks.

Cost Optimization : Use smaller models (e.g., Haiku) for simple work, keep team size between 2‑4 members, shut down idle teammates, and replace simple tasks with Subagents.

Logging & Debugging : View team config with cat ~/.claude/teams/{team‑name}/config.json, list tasks, tail logs, check teammate status, and manually update task states.

End‑to‑End Example: Building a Visual Analysis Platform

The tutorial walks through creating a three‑person team (frontend, backend, product‑manager) to build a platform that visualizes Agent Teams interactions, shows timelines, and generates graphs. Screenshots illustrate the tmux layout, task list, and progress monitoring.

Best‑Practice Summary

Define clear task boundaries for each member.

Provide sufficient context in spawn commands.

Monitor progress regularly.

Enable tmux mouse mode for smoother interaction.

Keep tasks appropriately sized.

Document decisions and maintain logs.

Validate incrementally rather than at the end.

What Not to Do

Create more members than necessary.

Allow multiple members to edit the same file.

Make tasks so small that a team is overkill.

Leave the team unsupervised for long periods.

Ignore errors; intervene promptly.

Mix in‑process and split‑pane modes in the same project.

Forget to clean up resources after completion.

Deploy without human review.

Troubleshooting

Stuck tmux Sessions

# List all tmux sessions
 tmux ls
# Kill a specific session
 tmux kill-session -t session-name
# Kill all sessions
 tmux kill-server

Unresponsive Teammates

# List active teammates
 claude list-teammates
# Show last 50 lines from a teammate
 claude logs JWT‑Specialist --tail 50

Task Stuck in "in‑progress"

# Manually mark task as completed
 claude task complete "implement-jwt-validation"
# Or have the Lead verify task status

Excessive Permission Prompts

Use the --dangerously-skip-permissions flag or pre‑approve common operations in the configuration.

Configuration File Example

{
  "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" },
  "teammateMode": "tmux",
  "permissions": { "read": "always_allow", "write": "prompt", "execute": "prompt" }
}

References

Claude Code Agent Teams documentation

Building a C compiler with a team of parallel Claudes

Claude Code GitHub Discussions

tmux official Wiki

Subagents documentation

Git worktrees and parallel sessions

Claude Code Hooks

Conclusion

Agent Teams is powerful but complex. After following this guide you should understand the core concepts, environment setup, common issues, and the full workflow from creation to cleanup, as well as advanced techniques and best practices. Use Agent Teams for complex, collaborative projects, and fall back to a single Claude session or Subagents for simpler tasks.