Skip to content

teams

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

teams

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
.claude-plugin
.claude-plugin
 
 
skills/teams
skills/teams
 
 
CHANGELOG.md
CHANGELOG.md
 
 
README.md
README.md
 
 

README.md

Teams Plugin

Orchestrate teams of Claude Code sessions working in parallel. One lead decomposes work, spawns teammates, assigns tasks with file ownership, and steers execution. Teammates work independently, each in its own context window, and communicate through a shared task list and direct messaging.

Unlike subagents, which run within a single session and can only report back to the main agent, you can also interact with individual teammates directly without going through the lead.

Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled in settings.

Display mode

The teammateMode setting controls how teammates are displayed:

Mode Behavior
"auto" (default) Split panes if inside tmux, in-process otherwise
"tmux" Force split panes (auto-detects tmux vs iTerm2)
"in-process" All teammates run inside the main terminal

Set in settings.json:

{ "teammateMode": "in-process" }

Or override per-session:

claude --teammate-mode in-process

Split-pane mode requires tmux or iTerm2 with the it2 CLI. Not supported in VS Code terminal, Windows Terminal, or Ghostty.

Note

tmux -CC in iTerm2 is the suggested entrypoint into tmux. tmux has known limitations on certain operating systems and traditionally works best on macOS.

Usage

This skill provides flags for controlling team behavior. These flags are skill-specific. They are not built-in Claude Code CLI flags.

/teams Refactor the auth module into separate concerns    # Spawn and execute
/teams --dry-run Build a notification system                # Plan only
/teams --plan-approval Migrate the database schema          # Teammates plan before implementing
/teams --delegate Review PR #42 from three angles           # Lead never implements
/teams --roles 3 Add caching to all API endpoints           # Force 3 teammates
Fully-qualified syntax

If another plugin has a conflicting skill name, use the full plugin:skill form:

/teams:teams <task> [--dry-run] [--plan-approval] [--delegate] [--roles N]

When to use

Agent teams are most effective for tasks where parallel exploration adds real value:

  • Research and review: multiple teammates investigate different aspects simultaneously, then share and challenge each other's findings
  • New modules or features: teammates each own a separate piece without stepping on each other
  • Debugging with competing hypotheses: teammates test different theories in parallel and converge on the answer faster
  • Cross-layer coordination: changes that span frontend, backend, and tests, each owned by a different teammate

If you're new to agent teams, start with tasks that have clear boundaries and don't require writing code: reviewing a PR, researching a library, or investigating a bug.

When NOT to use

Don't create a team for:

  • Trivial work: fewer than 3 files, obvious change
  • Sequential tasks: steps must happen in order, no parallelism
  • Same-file edits: two teammates editing one file causes overwrites
  • High dependency: most tasks block on each other

For these cases, a single session or subagents are more effective.

Architecture

An agent team consists of:

Component Role
Team lead The main Claude Code session that creates the team, spawns teammates, and coordinates work
Teammates Separate Claude Code instances that each work on assigned tasks
Task list Shared list of work items that teammates claim and complete
Mailbox Messaging system for communication between agents

How It Works

Phase 1: Reconnaissance

Reads CLAUDE.md, maps the codebase structure, identifies which files and modules the task touches, detects constraints (shared state, sequential dependencies).

Phase 2: Decomposition

Breaks work into independent units. Each unit touches a disjoint set of files, has a clear deliverable, and can be completed in isolation.

Phase 3: Team Design

Selects team composition from reference patterns:

Pattern When
Parallel Builders New feature spanning multiple modules
Review Panel Code review, security audit, PR review
Research Team Evaluating options, exploring architecture
Adversarial Debug Unknown root cause, competing hypotheses
Cross-Layer Changes spanning frontend, backend, database

Phase 4: Task Graph

Creates dependency-ordered tasks. Producers before consumers. Schemas before implementations. Interfaces before concrete types.

Phase 5: Spawn & Brief

Each teammate gets a spawn prompt with: role, owned files, context files, exclusions, task IDs, and communication rules. Teammates auto-load CLAUDE.md and MCP servers independently. The spawn prompt focuses on task-specific context.

Phase 6: Coordinate

Lead tracks progress, unblocks stuck teammates, redirects scope drift, and synthesizes results. Never implements.

Flags

Flag Effect
--dry-run Design team and task graph without spawning
--plan-approval Require teammates to plan before implementing. Use for schema changes, API modifications, and critical code paths. Lead approves or rejects each plan with feedback.
--delegate Restrict lead to coordination-only tools, no code editing
--roles N Force specific teammate count (max 5)

Tip

Use --dry-run to preview the team plan and task graph before spawning.

Tip

Use --delegate to prevent the lead from implementing tasks itself.

Interacting with teammates

In-process mode

Key Action
Shift+Up/Down Navigate between teammates
Enter View a teammate's session
Escape Interrupt a teammate's current turn
Ctrl+T Toggle the shared task list

Split-pane mode

Click into a teammate's pane to interact with their session directly.

Tip

The lead sometimes implements tasks itself instead of waiting for teammates. If this happens, tell it to wait, or use --delegate to restrict the lead to coordination-only tools.

Teammate configuration

Beyond name, role, model, and file ownership, teammates support:

Field Effect
mode default, acceptEdits, dontAsk, bypassPermissions, plan, auto
isolation worktree gives the teammate its own git worktree
maxTurns Cap the number of agentic turns
memory user, project, or local for persistent cross-session memory
mcpServers Scope specific MCP servers to this teammate

Token cost

Agent teams use 3-10x more tokens than a single session (roughly 7x in plan mode). Each teammate has its own context window (1M tokens with Opus 4.6 on Max/Team/Enterprise), and token usage scales with the number of active teammates. Use Sonnet for teammates when possible. Start with 3-5 teammates, target 5-6 tasks per teammate. For routine tasks, a single session is more cost-effective.

Limitations

Agent teams are experimental:

  • /resume and /rewind do not restore teammates. Spawn new ones after resuming.
  • Task status can lag. Teammates sometimes forget to mark tasks completed.
  • Shutdown can be slow. Teammates finish their current request or tool call before stopping.
  • One team per session. Clean up before starting a new one.
  • No nested teams. Teammates cannot spawn their own teams or teammates.
  • Lead is fixed. The session that creates the team leads it for its lifetime.
  • Teammates inherit the lead's permission mode by default. Use mode to override per-teammate at spawn, or change individually after spawning. If the lead runs with --dangerously-skip-permissions, all teammates inherit that setting.
  • Split panes require tmux or iTerm2 (not supported in VS Code terminal, Windows Terminal, or Ghostty)

Teammates read CLAUDE.md from their working directory. Use this to provide project-specific guidance to all teammates.

Troubleshooting

Symptom Fix
Teammates not appearing Task may be too simple for a team. In in-process mode, press Shift+Down to cycle through active teammates. For split panes, verify tmux is installed (which tmux).
Too many permission prompts Pre-approve common operations (file reads/writes, git, build/test commands) in permission settings before spawning.
Teammate stops on errors Message them with instructions, or spawn a replacement teammate to continue the work.
Lead implements instead of delegating Use --delegate, or tell the lead to wait for teammates to finish.
Lead shuts down before work is done The lead may decide the team is finished before all tasks are complete. Tell it to keep going, or tell it to wait for teammates to finish before proceeding.
Task appears stuck Check if the work is actually done. Teammates sometimes forget to mark tasks completed. Update manually or nudge the teammate.
Orphaned tmux sessions tmux ls then tmux kill-session -t <session-name>

Important

Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS enabled. Add to settings.json:

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