Claude Code Agent Teams: From Solo Agent to Coordinated Team

The OpenClaw community had found the goldmine before everyone else. They had built custom skills to orchestrate multiple Claude Code sessions in parallel on the same project. It worked, it was clever — and apparently, Anthropic took notes.

Because they just shipped exactly the same thing, natively in Claude Code. No plugin, no workaround. It’s integrated, and it’s called Agent Teams.

From solo agent to project manager with their team

Until now, Claude Code worked like a solo employee. You give it a job, it does step 1, then step 2, then step 3. Sequentially. One task at a time.

Agent Teams completely change the game.

You describe what you want, and instead of one agent grinding alone, a lead agent analyzes the task, breaks it into pieces, and spins up separate teammates to handle different parts at the same time.

• One teammate can explore your codebase
• While another debugs a function
• While a third writes tests

Each teammate has their own context window, their own workspace, and they can talk directly to each other to share discoveries.

The lead stays on top of all this: they coordinate, manage a shared task list, and assemble everything once teammates are done. And you can intervene directly on any teammate without going through the lead.

Sub-agents vs Agent Teams: the real difference

If you already use Claude Code, you know sub-agents. They spin up in your session, do a targeted task, and return the result to the main agent. Simple, efficient, light on tokens.

Agent Teams are a different animal.

	Sub-agents	Agent Teams
Session	In parent context	Independent session per teammate
Communication	Report to parent only	Talk to each other + lead
Coordination	None between sub-agents	Shared task list, direct messages
Token cost	Light	Significantly higher
Use case	Targeted task, quick answer	Complex multi-part work

The key question: do your workers need to communicate with each other?

• No → Sub-agents. Cheaper, faster.
• Yes → Agent Teams. The overhead is justified by collaboration.

If you want to understand how I was already using expert sub-agents via MCP before this update, I talk about it in my article on GLM Delegator and expert sub-agents.

When to use Agent Teams (and when it’s overkill)

Agent Teams are not a “use this for everything”. They add coordination overhead and burn tokens significantly faster than a solo session.

The sweet spots

• Research & review: multiple teammates investigate different angles of a problem in parallel, then compare notes
• Modular new features: each teammate owns a distinct module or file
• Multi-hypothesis debugging: instead of one agent following a single track (potentially the wrong one), multiple teammates test competing hypotheses. First to find wins
• Cross-layer work: one on frontend, one on backend, one on tests. Each owns their part

The anti-patterns

• Sequential work: if step 2 depends on step 1, no point in parallelizing
• Same file editing: two teammates on the same file = guaranteed overwrites
• Simple tasks: coordination overhead costs more than letting a solo agent do the job

Golden rule: before spinning up a team, ask yourself if the work can genuinely be broken into independent pieces. If yes, go. If not, a solo agent or sub-agents will do better for less cost.

Installation: 30 seconds

Agent Teams are experimental and disabled by default. Two options to enable them.

Option 1: settings.json (recommended)

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

Option 2: environment variable

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

The settings.json is cleaner if you want it to persist between sessions.

First launch: what to tell the lead

No special syntax to learn. You describe what you want in natural language and tell Claude to create a team.

I'm designing a CLI tool that helps developers track TODOs
in their codebase. Create an agent team to explore this from
different angles: one teammate on UX, one on technical
architecture, one playing devil's advocate.

The lead creates the team, spins up teammates, assigns them roles via the shared task list, and off we go.

The key to a good initial prompt

Be specific about what each teammate should focus on. The more precise, the fewer tokens the lead wastes structuring the work themselves.

You can also control the number of teammates and the model:

Create a team of 4 teammates to refactor these modules in
parallel. Use Sonnet for each teammate.

Two display modes

• In-process (default): all teammates run in your main terminal. Shift+Up/Down to navigate between them
• Split-pane: each teammate has their own pane (requires tmux or iTerm2)

Controlling your team live

Talking directly to a teammate

No need to go through the lead. In in-process: Shift+Up/Down to select, then type. In split-pane: click in the pane.

Delegate mode (important)

Sometimes the lead decides to do the work themselves instead of delegating. Delegate mode locks them into coordination-only: they can only spawn teammates, assign tasks, and send messages.

→ Shift+Tab to activate.

Task management

Tasks can be assigned by the lead or auto-claimed by teammates. When a teammate finishes their task, they can automatically take the next unassigned one in the list.

Clean shutdown

When a teammate is done: ask the lead to shut them down. The lead sends a shutdown_request, the teammate confirms, and they exit cleanly. Once all teammates are stopped, the lead can cleanup shared resources.

Best practices to not burn your tokens

1. Detailed spawn prompts

Teammates automatically load project context (CLAUDE.md, MCP servers), but they don’t inherit the lead’s conversation history. All necessary context must be in the spawn prompt.

2. Well-sized tasks

• Too small → coordination overhead costs more than the benefit
• Too big → teammate works too long without check-in, risk of wasted work
• Sweet spot → an autonomous unit with a clear deliverable (one function, one test file, one review)

3. One file per teammate

Two teammates on the same file = overwrites. Break the work so each owns their own files.

4. Start with research/review

Before diving into parallel implementation, test with review tasks. Have a PR reviewed from different angles, or investigate a bug with competing hypotheses. It shows the value of parallelism without the complexity of code coordination.

5. Regular check-in

Don’t let the team run too long without supervision. The longer a teammate goes in a wrong direction without correction, the more tokens you waste.

Current limitations (research preview)

No dealbreakers, but you need to know them:

• Broken session resumption: /resume and /rewind don’t bring back in-process teammates. If it happens, tell the lead to spawn new ones
• Lagging task status: sometimes a teammate finishes their work but doesn’t mark the task as done, which blocks dependencies. Verify manually if needed
• One team per session: teammates can’t spawn their own teams. The team creator remains the lead for its entire lifetime
• Limited split-pane: only works with tmux or iTerm2. Not supported in VS Code integrated terminal, Windows Terminal, or Ghostty

What this actually changes

Agent Teams are the shift from “one freelancer who does everything” to “a project manager who arrives with their team”. It’s the logical next step from what the community had already built — and it’s now native.

Combined with tools like GLM Delegator for MCP experts, and good integration of AI in daily workflow, we reach a setup where Claude Code is no longer an assistant, it’s an orchestrator that manages a team of specialized agents.

Going further: GLM Delegator + Agent Teams

Agent Teams handle native coordination between agents. But to add specialized experts (architecture, security, code review) to your teammates, you can combine this with GLM Delegator — an MCP server that exposes 5 expert agents in Claude Code.

GLM Delegator uses the GLM-4.7 model via Z.AI, which offers a plan dedicated to coding tools (Claude Code, Cline, and 10+ tools) starting at $3/month. This is what powers ccm-manager and the repo experts.

→ Subscribe to GLM Coding Plan on Z.AI

The combo of native Agent Teams + GLM Delegator experts via MCP gives a setup where each teammate can consult a specialized expert during their work. The frontend dev asks for a security opinion, the backend dev gets their architecture validated — all in parallel.

It’s in research preview. It’s rough around the edges. But those who start building their muscle memory now will have a head start when it goes stable.

Official documentation: code.claude.com/docs/en/agent-teams