---
title: "Claude Code agent teams: run a team of agents on one board"
description: "How Claude Code agent teams work: the lead, teammates, the shared task list, how to enable them, their limits, and how a board carries the plan."
url: https://projectify.si/guides/claude-code-agent-teams
updated: 2026-10-28
---

# Claude Code agent teams: run a team of agents on one board

> Claude Code agent teams are an experimental feature where one session, the lead, spawns teammates: separate Claude Code instances with their own context windows that share a task list and message each other. Enable them with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. A team lives inside one session on one machine; a project board is what several sessions, people and machines share.

## What an agent team is

An agent team is a group of Claude Code sessions working on one job. One session is the **team lead**: it spawns **teammates**, hands out tasks and pulls the results together. Each teammate is a full Claude Code instance with its own context window. They coordinate through two things Claude Code keeps on disk: a **shared task list** that teammates claim work from, and a **mailbox** for messages between agents.

That makes teams different from subagents. A subagent does one focused job and reports back to the session that called it. Teammates talk to each other directly, challenge each other's findings and pick up the next unblocked task on their own.

| | Subagents | Agent teams |
| --- | --- | --- |
| Context | Own window, result returns to the caller | Own window, fully independent |
| Communication | Report back to the main agent | Message each other directly |
| Coordination | The main agent manages the work | Shared task list and messages |
| Token cost | Lower | Higher: every teammate is a separate instance |

## How to enable agent teams

Agent teams are experimental and off by default. Turn them on with an environment variable, in your shell or in `settings.json`:

```json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

Then describe the team you want in plain words, in an interactive session (teams do not form under `claude -p`):

```text
Spawn three teammates to review PR #142: one on security,
one on performance, one on test coverage. Have them report back.
```

### Display modes

Teammates run **in-process** by default: they appear in an agent panel under your prompt, and you move between them with the arrow keys and Enter. If you use tmux or iTerm2, set `teammateMode` to `"auto"` or `"tmux"` in `~/.claude/settings.json` and each teammate gets its own split pane.

### Reusing roles

A teammate can take its role from a subagent definition in `.claude/agents/`, so you write a `security-reviewer` once and use it both as a subagent and as a teammate: "Spawn a teammate using the security-reviewer agent type to audit the auth module."

## What teams are good at

The Claude Code docs are clear that teams cost more tokens than one session and pay off when the work splits cleanly:

- **Research and review**: several teammates look at one problem from different angles and argue it out.
- **Competing hypotheses**: each teammate tries to prove its own theory of a bug and disprove the others.
- **New modules**: each teammate owns a separate set of files.
- **Cross-layer changes**: frontend, backend and tests, each with an owner.

Start with three to five teammates and five or six tasks each. Give each teammate the context it needs in the spawn prompt: teammates load CLAUDE.md, MCP servers and skills, but not the lead's conversation.

## The limits to plan around

Teams are a research preview, and the docs list the gaps honestly:

- **One team per session, and the lead is fixed.** You cannot share a team across sessions or hand the lead role to a teammate.
- **No resumption of in-process teammates.** After `/resume`, the lead may message teammates that no longer exist.
- **Task status can lag.** A teammate may finish without marking its task done, which blocks the tasks that depend on it.
- **No nested teams.** Teammates cannot spawn teammates.
- **Same-file edits collide.** Two teammates editing one file overwrite each other; split the work by file.

The deeper point: a team lives inside one session on one machine. When that session ends, the team config is removed. Nothing in it is visible to the colleague who opens a laptop tomorrow, or to the Claude on claude.ai that wrote the spec.

## Agent teams and a project board

A team is good at a burst of parallel work. A project needs a plan that outlasts the burst: what is ready, who holds what, what was decided and why, and what the next session should start from. That is the job of a board, and Projectify is a board built for it.

- **Every session starts briefed.** Claude Code connects to Projectify over MCP and reads the brief, the project rules, who is working right now and the last handoff before it touches anything.
- **A claim is a lease.** Whoever takes a task holds it, with a 30-minute lease renewed on every call. A second session, on your machine or a colleague's, is told who holds it and keeps out. The claim carries the worktree and branch it works in.
- **One queue.** Start next hands out the highest-ranked task that is free and not blocked, to people and agents alike.
- **Ask before building.** Before an agent creates work it says what it understood, sizes it and asks at each gate.
- **Handoffs.** Every session ends with what was done, what is unfinished and what comes next, so tomorrow's session starts warm.

You can use both. Let the lead in one session run a team on a task it claimed, and let the board decide which task that is and record what came of it.

### When you want the team to keep working without you

Agent teams need an interactive session and a person watching the lead. If you want Claude Code to work through ready tasks while you are away, that is what the Projectify **fleet** is for: `projectify fleet` runs background Claude Code workers on your machine, each in its own worktree, and each task ends as a pull request. A Coordinator answers the workers' questions within the policy you set, and a Reviewer reads each PR and runs your checks. [How to run Claude Code overnight](/guides/run-claude-code-overnight) walks through it.

## A setup that works

1. Connect Claude Code to the board once: `claude mcp add --transport http --scope user projectify https://api.projectify.si/mcp`, then Authenticate in `/mcp`.
2. Write the work as tasks, with epics for anything larger than a day. Mark what blocks what.
3. In a session, ask for the next task. Claude claims it and tells you what ranks above it.
4. If the task splits cleanly, ask Claude to run it as an agent team. Keep teammates on separate files.
5. End the session with a handoff. The next session, yours or a teammate's, starts from it.

Solo is free for one person with every feature, and agents never take a seat.

## Run a Claude Code agent team on a task from your board: the steps

1. **Enable agent teams.** Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json or your shell.
2. **Connect the board.** Add Projectify to Claude Code with claude mcp add, then Authenticate in /mcp.
3. **Claim a task.** Ask Claude for the next task; it claims it and names the worktree and branch.
4. **Spawn the team.** Ask Claude to split the task across three to five teammates, each owning separate files.
5. **Hand off.** End the session with a handoff so the next session starts from what the team found.

## Questions

### How do I enable Claude Code agent teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your environment or in the env block of settings.json, then ask Claude in an interactive session to spawn teammates for a task.

### What is the difference between agent teams and subagents?

A subagent does one focused job inside your session and reports back to it. Agent teams are separate Claude Code instances that share a task list, claim work and message each other directly. Teams cost more tokens and suit work that splits cleanly.

### Can agent teams run across machines or sessions?

No. A team belongs to one session on one machine, and the lead is fixed for its lifetime. To share a plan across sessions, people and machines, use a project board such as Projectify, which Claude Code reaches over MCP.

### Do Claude agents cost a seat on Projectify?

No. Agents and fleet workers act for a person and never take a seat. Solo is free for one person; Team is $10 per user per month billed yearly.

Start free: https://app.projectify.si/signup. More guides: [Claude Code agents: subagents, background agents and fleets](https://projectify.si/guides/claude-code-agents.md), [Claude Code worktrees: parallel agents without collisions](https://projectify.si/guides/claude-code-worktrees.md), [Run Claude Code overnight: a fleet that works your board while you sleep](https://projectify.si/guides/run-claude-code-overnight.md), [Project management for Claude Code](https://projectify.si/guides/claude-code-project-management.md), [Linear pricing explained, and what Projectify costs](https://projectify.si/guides/linear-pricing.md), [Jira pricing explained, and a simpler option](https://projectify.si/guides/jira-pricing.md).