How To Use Agent Teams In Claude Code To Have Multiple “Claudes” Work On Your Project At Once

Listen to this article

Agent Teams (also known as “Swarm Mode”) is a powerful feature in Claude Code that allows you to spin up multiple independent “teammates” that work in parallel, communicate with each other via a mailbox system, and coordinate through a shared task list.

Unlike standard subagents that only report back to a lead, Agent Teams actually collaborate to solve complex, multi-file problems like full stack feature development or deep security audits.

1. Enable Agent Teams

As of early 2026, this is an experimental feature and must be explicitly enabled in your settings.

1. Open your settings file: code ~/.claude/settings.json.
2. Add the experimental flag to your global configuration:
3. {
4.    “env”: {
5.        “CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS”: “1”
6.     }
7. }
8. Restart your terminal session.

2. Launch Your First Team

You don’t configure teams manually; you describe the “vibe” and the roles in natural language. Claude Code (the Team Lead) will then decompose the work into a shared task list and spawn the specialists.

Example Prompt:

“Create an agent team to build a new ‘User Dashboard’ feature. Spawn 3 teammates: 1. Frontend specialist for React/Tailwind, 2. Backend specialist for the API endpoints, and 3. QA specialist to write Playwright tests. Have them coordinate on the API contract before starting.”

3. Controlling the Team

Once the team is running, you can monitor and interact with individual Claudes:

Navigation: Use Shift + Down (or Up) to cycle through your teammates in the terminal.

Direct Messaging: When a teammate is selected, you can type to message them directly, giving them specific feedback without bothering the rest of the team.

Task List: Press Ctrl + T to see the shared task list, which tracks what is “pending,” “in progress,” or “completed”.

Display Modes:

• In-process (Default): All teammates run in one terminal window; you switch views with shortcuts.
• Split Panes (Recommended): If you have tmux or iTerm2 installed, use claude –teammate-mode tmux to see every agent working in its own terminal pane simultaneously.

4. Best Practices for “Swarming”

• Task Sizing: Aim for 5–6 tasks per teammate. If tasks are too small, the team spends more time talking than coding.
• Avoid Conflicts: Assign different folders or files to different agents (e.g., /src/client vs /src/server) to prevent them from overwriting each other’s work.
• Plan Approval: For risky changes, tell the lead: “Require plan approval before teammates make any edits.” The lead will review their plan and ask for your “OK” before they touch the code.
• Cleanup: Always ask the Team Lead to “clean up the team” when finished to ensure all temporary files and sessions are closed properly.

Warning: Agent Teams are token-intensive. Each teammate has its own 1M token context window, so a team of five can burn through your usage limits 5x faster than a single session.

Deep Dive Into “Swarm Mode”

Agent Teams, popularly known as “Swarm Mode,” is a multi-agent orchestration system that transforms Claude Code from a single assistant into a coordinated squad of AI specialists. Unlike standard sub-agents that follow a strict “fire and forget” hierarchy, Agent Teams operate as a peer to peer organization with direct communication and shared state.

1. The “Swarm” Architecture

The system is built on four interconnected components that enable autonomous parallel work:

1. Team Lead: Your main session acts as the “Architect.” It analyzes the goal, decomposes it into a Directed Acyclic Graph (DAG) of tasks, and monitors the overall progress.
2. Specialized Teammates: These are fully independent Claude Code instances. Each has its own 1M-token context window, meaning they don’t get “confused” by the Lead’s entire conversation history—only what they need for their specific task.
3. Shared Task List: This is the team’s “Kanban board,” stored as a local file (typically in ~/.claude/tasks/). It tracks task states (pending, in-progress, completed) and dependencies to ensure agents don’t work out of order.
4. Mailbox System: This is the breakthrough for “Swarm” behavior. Agents communicate peer to peer via JSON messages in a shared directory (~/.claude/teams/). They can @mention teammates to share findings, challenge logic, or coordinate API contracts mid-task.

2. Technical Conflict Resolution

The hardest part of parallel coding is preventing two agents from editing the same file. Claude Code solves this with:

• Git Worktrees: Each agent works in its own separate Git worktree (a separate directory backed by the same repo). This allows them to commit and test independently without interfering with each other’s file system.
• File Locking: The task list uses file-based locking to prevent race conditions when multiple agents try to “claim” the same task at once.

3. Performance & Efficiency

• Context Optimization: In single agent mode, Claude often uses 80–90% of its context window on large projects. In Agent Teams, each specialist typically uses only 40%, leading to fewer hallucinations and faster responses.
• Throughput: Teams report a 5x to 10x increase in development speed for large refactors and comprehensive test suites.
• The “Opus 4.6” Requirement: Swarm mode is optimized for Claude 3.7/4.6 Opus, which provides the advanced reasoning needed to handle complex delegation and peer to peer messaging.

You can learn how to use Claude Opus 4.7 using step by step guide.

4. When to Use (and When Not To)

Pro Tip: Use the split-pane display mode (requires tmux or iTerm2) to see every agent’s terminal in real time. This provides the “Mission Control” visibility necessary to debug the swarm if it gets stuck.