Claude Code Agent Teams: 5-Team Setup and Production Guide

How Agent Teams differ from subagents

On February 5, 2026, Anthropic announced Agent Teams, a new experimental feature for Claude Code. Subagents run within a single session and can only report results back to the caller. Agent Teams work differently. They consist of fully independent Claude Code instances that communicate directly with each other.

Here’s the key difference:

I tested it in my OpenClaw environment the same day it dropped. This post documents the whole process: the setup, the stumbling blocks, and what I learned along the way.

Prerequisites: the OpenClaw dev build

Agent Teams requires the latest Claude Code. At the time, OpenClaw’s stable channel had a cron job bug that needed fixing anyway, so switching to the dev channel killed two birds with one stone. (Related post)

Enable pnpm

corepack enable pnpm

Switch to dev channel and build from source

export OPENCLAW_GIT_DIR=~/openclaw
openclaw update --channel dev

If the automatic update fails, build manually:

cd ~/openclaw
pnpm install && pnpm build && npm install -g .

Restart the gateway

openclaw gateway restart

This gets you on dev channel v2026.2.4, which includes the Claude Code version that supports Agent Teams.

Enabling Agent Teams

Agent Teams are disabled by default. Two ways to enable them:

Option 1: Environment variable

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Option 2: Persistent setting in settings.json

~/.claude/settings.json:

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

For OpenClaw LaunchAgent users

If you run OpenClaw as a macOS LaunchAgent, add the variable to your plist file’s EnvironmentVariables section so it persists across gateway restarts:

<key>EnvironmentVariables</key>
<dict>
    <key>CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS</key>
    <string>1</string>
</dict>

I went with the settings.json approach. Environment variables vanish between sessions; settings.json gets loaded automatically every time Claude Code starts.

Configuring teammateMode

Agent Teams supports three display modes:

• in-process: All teammates run inside the main terminal. Use Shift+↑/↓ to select teammates.
• tmux: Each teammate gets its own tmux split pane. See everyone’s output at once.
• iTerm2: Auto-splits when running in iTerm2.

The default is auto: split panes if you’re already in tmux, in-process otherwise.

I explicitly set tmux mode:

{
  "teammateMode": "tmux"
}

The reasoning is straightforward: when running 5 teams simultaneously, you need to see each teammate’s progress in real time on one screen to catch bottlenecks quickly.

If tmux isn’t installed:

brew install tmux

How I split the five teams

Here’s how I structured the five teams and the thinking behind each.

1. ops (Operations)

Infrastructure checks, gateway health monitoring, cron job verification. Especially critical right after the dev channel switch.

2. branding

Blog post creation, hero image generation, multilingual content management. This team produces technical content in 4 languages (EN/KO/JA/ZH) simultaneously.

3. invest (Investment)

Market analysis, portfolio review, and risk assessment, all running in parallel.

4. dev (Development)

Code review, refactoring, test writing, feature implementation. The key here is clearly separating each teammate’s module ownership to prevent file conflicts.

5. social

Social media draft creation, trend analysis, community monitoring.

Example team setup prompt:

Create 5 agent teams:
- ops: Infrastructure operations and monitoring
- branding: Content production and multilingual management
- invest: Market analysis and investment research
- dev: Code writing and review
- social: SNS and community management
Assign 2 teammates to each team using the Sonnet model.

Task Lists and Dependency Management

One of Agent Teams’ core mechanisms is the shared task list. The team lead creates tasks, and teammates autonomously claim and process them.

Task states

• pending: Waiting to be picked up
• in progress: Currently being worked on
• completed: Done

Dependencies

When you set up task dependencies, downstream tasks can’t be claimed until their prerequisites are complete.

Real example:

Task list:
1. [ops] Gateway health check
2. [ops] Cron job verification (→ depends on #1)
3. [branding] Blog draft writing
4. [branding] Hero image generation
5. [branding] Multilingual translation (→ depends on #3)
6. [dev] Recommendation system refactoring
7. [dev] Test writing (→ depends on #6)

Task claiming uses file locking to prevent race conditions when multiple teammates try to grab the same task simultaneously.

Running in Production

Delegate mode

By default, the team lead can do work directly. Delegate mode restricts the lead to coordination only:

• Spawning/shutting down teammates
• Relaying messages
• Managing tasks

Enable it with Shift+Tab.

For large teams, delegate mode is strongly recommended. When the lead starts coding, coordination gaps appear.

Talking to teammates directly

You can bypass the lead and message any teammate:

• in-process: Shift+↑/↓ to select, then type
• tmux: Click into the teammate’s pane

Plan approval

For critical work, require teammates to plan before executing:

Create an architect teammate for the auth module refactor.
Require plan approval before any changes.

The lead reviews and approves or rejects with feedback.

Where OpenClaw and Agent Teams meet

Here’s what makes this interesting. OpenClaw’s multi-agent capabilities and Agent Teams operate at different layers.

OpenClaw Multi-Agent

• Manages agents at the channel level (Telegram, Discord, etc.)
• Each agent has its own persona and configuration
• Supports automated scheduling via cron jobs and heartbeats

Claude Code Agent Teams

• Collaboration at the session level across multiple Claude Code instances
• Shared task list and messaging system
• Optimized for parallel code work

Combining both layers:

OpenClaw Agent (channel level)
  └─ Claude Code session
       └─ Agent Team (session level)
            ├─ Teammate A (ops)
            ├─ Teammate B (branding)
            └─ Teammate C (dev)

The pipeline: OpenClaw’s main agent receives a Telegram message, spawns a subagent, that subagent sets up an Agent Team for parallel processing, then delivers results back through Telegram.

Best Practices

1. Prevent file conflicts

The biggest pitfall is multiple teammates editing the same file.

• Clearly separate directory/file ownership per teammate
• Use task dependencies to ensure shared files have a single writer
• Check team config in .claude/teams/

2. Context handoff

Teammates auto-load CLAUDE.md, MCP servers, and skills, but they don’t inherit the lead’s conversation history. So:

• Include sufficient context in spawn prompts
• Explicitly reference relevant file paths
• Add team-wide information to CLAUDE.md if needed

3. Token management

Each teammate uses its own context window, so token consumption spikes fast.

• Use subagents for simple tasks
• Reserve Agent Teams for discussion, review, and parallel exploration
• Minimize broadcast messages, since cost scales with team size

4. Permission management

Teammates inherit the lead’s permission settings. If the lead runs with --dangerously-skip-permissions, every teammate does too. Be careful.

Limitations and Caveats

1. Experimental feature: The EXPERIMENTAL in the env var name says it all. The API may change.

2. Token cost: A 5-person team means at least 5x token consumption. Calculate your ROI.

3. Debugging complexity: Multiple teammates working simultaneously makes root cause analysis harder.

4. Inefficient for sequential work: Tasks with heavy dependencies end up running serially anyway — no point using teams.

5. Same-file editing risk: There’s no file-level locking yet. You have to work around this through task design.

6. tmux is practically required: Monitoring 5 teams in in-process mode is painful. tmux is the way to go.

When to Use It, When to Avoid It

The official docs only recommend Agent Teams for work where parallel exploration adds real value. After a day of running it, here’s the line I’d draw.

Good fits

• Splitting a code review into independent lenses (security, performance, test coverage) and running them at once
• Debugging an unclear root cause by testing competing hypotheses in parallel and having teammates challenge each other
• New features that span layers (frontend, backend, tests), with one teammate owning each
• Research like surveying a library, where you gather and compare findings afterward

Avoid when

• The work has heavy dependencies and ends up serial anyway. A team won’t make it faster.
• Multiple teammates need to touch the same file. There’s no file locking, so overwrites are a real risk.
• It’s simple, repetitive work. A single subagent handles that with far fewer tokens.
• You’re cost-sensitive. A 5-person team is at least 5x the tokens.

If you’re starting out, begin with review and research tasks that don’t write code. The boundaries are clear, so you feel the value of parallel collaboration with the least risk.

Related Reading

A few posts that approach the same multi-agent territory from other angles.

• Improving Multi-Agent Orchestration — goes a level deeper into the patterns for coordinating agents.
• Running Parallel Claude Code Sessions with Git Worktrees — the manual alternative to running parallel sessions without Agent Teams.
• The Reality of AI Agent Costs — weighs the economics of multi-agent setups where token costs spike.

Primary Sources

• Claude Code — Agent Teams (official docs)
• Claude Code — Subagents (official docs)
• Claude Code Overview

What a day with it taught me

Agent Teams are still experimental, but the potential is clear. Combined with OpenClaw’s multi-agent architecture, you get a dual-layer system: channel-level automation sitting on top of session-level parallel collaboration.

That said, throwing Agent Teams at every task right now would be wasteful. The scenarios that pay off are the ones where independent work piles up and teammates actually argue their way to a better answer. Parallel exploration. Code review. Competing hypothesis testing. Focus there.

Setup takes 30 minutes. The hard part is something else entirely: deciding what to team up and how to decompose tasks. That intuition only comes from getting your hands dirty.