/team-agents — Coordinated Agent Teams

Config

// ~/.claude/settings.json — required
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

// ~/.claude.json — display mode (default: "auto")
{ "teammateMode": "in-process" }   // all in main terminal
{ "teammateMode": "tmux" }         // split panes (requires tmux/iTerm2)

claude --teammate-mode in-process   # per-session override

Requires Claude Code v2.1.32+. Without env var, TeamCreate/SendMessage/TaskList tools don't exist — fall back to parallel subagents.

In-process keys: Shift+Down cycle teammates, Enter view, Escape interrupt, Ctrl+T toggle tasks.

Quality Gate Hooks

// ~/.claude/settings.json
{
  "hooks": {
    "TeammateIdle": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }],
    "TaskCreated": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }],
    "TaskCompleted": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }]
  }
}

Exit code 2 from any hook = reject action + send feedback to agent.

Usage

/team-agents "review this PR for security, perf, and tests"
/team-agents "refactor auth module" --roles 3
/team-agents "research X" --model haiku
/team-agents "implement feature Y" --plan
/team-agents --manual "build feature Z"
/team-agents --manual "build feature" --worktree

/team-agents who                    # presence dots + task state
/team-agents --panes                # tmux pane scan
/team-agents zoom scout             # toggle zoom on agent's pane
/team-agents sync                   # git sync all worktrees to main
/team-agents merge scout            # merge agent's branch to main
/team-agents compile                # gather all reports
/team-agents shutdown               # graceful shutdown
/team-agents cleanup                # kill idle orphan panes
/team-agents killshot               # kill ALL non-lead panes
/team-agents doctor [--fix]         # detect ghosts + orphans

When to Use

Rule: /team-agents = tmux panes. Plain Agent() = quiet subagents. The user's choice of invocation decides the tier. Sizing: 3-5 teammates, 5-6 tasks each. Tokens scale linearly per teammate.

Spawn Fallback Order

When the user explicitly invokes /team-agents, they want tmux panes. Never downgrade to Tier 3 when Tier 1 or 2 preflight passes — even for "read-only" or "simple" tasks. The user typed /team-agents because they want to SEE agents working. If they wanted quiet subagents, they'd just ask without the skill.

Try tiers in order. Stop at the first whose preflight passes — never skip ahead.

Tier 1 — tmux + team-agents framework (preferred)

Preflight — verify all four before TeamCreate:

[ -n "$TMUX" ] || tmux info >/dev/null 2>&1                       # 1. inside tmux?
[ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" = "1" ]                  # 2. env var set?
# 3. TeamCreate tool loaded? (deferred — ToolSearch select:TeamCreate,TaskCreate,SendMessage,TaskUpdate,TaskList,TeamDelete)
# 4. claude --version >= 2.1.32

All four pass → real team. Teammates spawn into split tmux panes with isolated heartbeats, SendMessage each other, get persistent mailboxes, can claim per-agent worktrees.

Tier 2 — in-process team-agents (env + tools, but no tmux)

env var + tools present but $TMUX empty → set teammateMode: "in-process" (per-session: claude --teammate-mode in-process) and proceed with TeamCreate. All teammates run in the main terminal — cycle with Shift+Down, view with Enter. Same coordination machinery, less visual separation.

Tier 3 — parallel subagents (Agent tool, ONLY when preflight fails)

env var missing, tools didn't load, or version too old → fall back to plain Agent tool calls. Never choose Tier 3 because the task "seems simple" or "read-only" — that's the user's call, not yours.

• Spawn N parallel Agent calls in a single message — same role prompts, no SendMessage/TaskUpdate
• Each agent returns its report as the tool result
• Lead synthesises in the same turn

Only used when: Tier 1/2 preflight fails (no tmux, no env var, CLI too old). Never chosen based on task complexity — /team-agents means the user wants the full framework.

Decision rule

/team-agents = user wants tmux panes. Period.
Tier 3 is a fallback for broken environments, not an optimization for simple tasks.

If Tier 1 preflight passes → use Tier 1. Always. The user opted into the token cost by typing /team-agents.

Subagent Definitions

Reference .claude/agents/ definitions when spawning: honors tools + model. Team tools (SendMessage, TaskUpdate) always available. skills/mcpServers frontmatter NOT applied to teammates.

Lifecycle

1. Create Team

TeamCreate("team-name")   // slugified from task

2. Create Tasks (with dependencies)

TaskCreate({ subject: "Security review", description: "..." })
TaskCreate({ subject: "Perf review", description: "..." })
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // task 2 waits for 1

3. Spawn Teammates

Spawn all in parallel via Agent tool. Prompt template (every teammate gets this):

You are the [ROLE] specialist on team "[TEAM_NAME]".

REPO: [WORKTREE_PATH if --worktree, else ABSOLUTE_PATH_TO_MAIN_REPO]
TASK: [TASK_DESCRIPTION]
COLOR: [AGENT_COLOR — e.g. blue, green, yellow]
WORKTREE: [yes — write freely | no — do NOT write files]

Instructions:
1. Do your work
2. Mark task done: TaskUpdate({ taskId: [ID], status: "completed" })
3. Report to lead: SendMessage({
     to: "team-lead@[TEAM_NAME]",
     summary: "[5-10 words]",
     message: "[findings, max 500 words]"
   })

HEARTBEAT — strict Bash:SendMessage alternation (1:1 ratio):

After EVERY Bash tool call (whether success or failure), your VERY NEXT tool
call MUST be SendMessage to team-lead. Pattern:

  Bash(...) → tool_result → SendMessage(to: team-lead, summary: "...",
  message: "<1-2 lines: what you did + what you saw>") → next Bash → ...

This is not optional. If you call two Bash in a row without a SendMessage
between them, the protocol is broken — self-ABORT with reason "skipped
heartbeat" and stop.

Special triggers (still subject to per-Bash heartbeat):
- STUCK: <what blocks you>  (when blocked, before any diagnostic Bash)
- DONE: <final summary>     (only after TaskUpdate marks task completed)
- ABORT: <reason>           (if you cannot proceed)

Avoid long shell loops inside a single Bash — prefer one Bash per iteration
step with mandatory heartbeat between. The lead counts your Bash:SendMessage
ratio. Silence = bug.

Rules:
- ALWAYS SendMessage BEFORE finishing
- If worktree: write to YOUR worktree only
- If shared repo: do NOT write files
- Max 500 words per report
- Be specific — paths, lines, evidence

Critical: Always include literal REPO: path (never shell vars), COLOR: from spawn opts, team-lead@[TEAM_NAME], heartbeat protocol, 500-word limit.

4. Wait + Compile

• Idle notifications are normal — teammates are working
• Real content arrives via SendMessage with summary
• If teammate crashes: SendMessage to stopped agent auto-resumes from disk transcript
• isActive() always returns true for tmux agents (bug) — check pane directly if suspect dead

Compile into:

# [Task] — Team Report
**Team**: [name] | **Agents**: [N] | **Duration**: ~[N]min
## [Role]: [Summary]    (per agent)
## Synthesis            (lead's cross-cutting observations)
## Action Items

5. Shutdown Strategies

Strategy A: All-at-once (default) — wait for all agents, then shutdown all:

# After ALL agents report DONE:
SendMessage({ to: "agent-1", message: { type: "shutdown_request" } })
SendMessage({ to: "agent-2", message: { type: "shutdown_request" } })
# Wait for shutdown_response (~10s)
TeamDelete()

Don't write the loop by hand — structured messages can't broadcast (#212), but the helper script generates the per-agent SendMessage block for you:

bash ~/.claude/skills/team-agents/scripts/broadcast-shutdown.sh $TEAM
# → prints ready-to-paste SendMessage lines, one per teammate (lead excluded)
# → also supports --names (raw list) and --json (array) for scripted loops
# → --type=X to broadcast any structured message type, not just shutdown

Strategy B: Rolling shutdown — shutdown each agent as it completes:

# On each DONE report: immediately shutdown that agent
SendMessage({ to: "agent-1", message: { type: "shutdown_request" } })
# Keep other agents running
# When LAST agent reports → shutdown + TeamDelete

Use when: agents are independent, no cross-agent dependencies. Saves tokens — idle agents still consume context.

Strategy C: Cron check — for long-running teams (10+ min):

# Schedule a periodic check via /loop or ScheduleWakeup
Every 2-5 min: check TaskList
  - If all tasks completed → shutdown all + compile
  - If some done, some stuck → nudge stuck agents
  - If all working → skip, check again next cycle

Use when: team runs > 10 min, lead doesn't want to block waiting.

Strategy D: TeammateIdle hook (system-level):

// ~/.claude/settings.json
{ "hooks": { "TaskCompleted": [{
  "matcher": "", "hooks": [{
    "type": "command",
    "command": "bash -c 'DONE=$(ls ~/.claude/tasks/*/completed 2>/dev/null | wc -l); TOTAL=$(ls ~/.claude/tasks/*/ 2>/dev/null | wc -l); [ \"$DONE\" = \"$TOTAL\" ] && echo ALL_DONE'"
  }]
}]}}

Exit code 0 + stdout "ALL_DONE" → lead knows to shutdown. Most reliable, no polling.

Pick based on team duration:

**Post-shutdown** (always run all 3):

Archive findings to persistent mailbox

for agent in $AGENTS; do bash ~/.claude/skills/mailbox/scripts/mailbox.sh archive $agent $TEAM done

Archive ephemeral skills to /tmp

bash ~/.claude/skills/team-agents/scripts/shutdown-skills.sh $TEAM $AGENTS

Sweep worktrees (catches crashed sessions — #336)

bash ~/.claude/skills/team-agents/scripts/shutdown-worktrees.sh "$REPO_PATH"

**Rules**: Never skip shutdown. Never broadcast shutdown. Always sweep worktrees. Teams this-session auto-clean on exit; prior-session teams persist and can resume.

---

## Manual Mode (`--manual`)

Agents spawn in standby — human directs each one via lead relay.

**Standby prompt** (replace standard prompt):

You are [ROLE] on team "[TEAMNAME]" in MANUAL mode. REPO: [PATH] COLOR: [AGENTCOLOR — e.g. blue, green, yellow] Wait for instructions. On each message:

1. Execute the work
2. SendMessage report to team-lead@[TEAM_NAME]
3. Return to standby

**Create live skills** so user can `/agent-name` directly:

bash ~/.claude/skills/team-agents/scripts/spawn-skills.sh $TEAM $AGENTS

**Pre-load mailbox** if agent has previous findings:

MAILBOX=$(bash ~/.claude/skills/mailbox/scripts/mailbox.sh load $AGENT 2>/dev/null)

---

## Worktree Mode (`--worktree`)

### Mode 1: `--worktree` flag (recommended)

REPOROOT=$(git rev-parse --show-toplevel) for AGENT in $AGENTS; do git branch "agents/$AGENT" HEAD 2>/dev/null || true git worktree add "$REPOROOT/agents/$AGENT" "agents/$AGENT" 2>/dev/null done

Agent prompt gets `REPO:` set to worktree path. Merge via `/team-agents merge <agent>`.

### Mode 2: `isolation: "worktree"` in Agent tool

Agent({ name: "builder", isolation: "worktree", ... })

Creates at `.claude/worktrees/agent-<id>`. Auto-cleaned if no changes. Prefer Mode 1.

---

## Subcommands

### who — Presence Dots

| Dot | State | Meaning |
|-----|-------|---------|
| `●` | active | Heartbeat < 5 min |
| `◐` | idle | Heartbeat 5-10 min |
| `◌` | working | In progress |
| `⊘` | stuck | Reported STUCK |
| `✓` | done | Reported DONE |
| `✗` | aborted | Reported ABORT |
| `·` | silent | No heartbeat > 10 min — investigate |

### Scripts

bash ~/.claude/skills/team-agents/scripts/panes.sh [team] # pane scan bash ~/.claude/skills/team-agents/scripts/cleanup.sh # kill idle panes bash ~/.claude/skills/team-agents/scripts/cleanup.sh --dry-run # preview bash ~/.claude/skills/team-agents/scripts/killshot.sh # kill ALL non-lead bash ~/.claude/skills/team-agents/scripts/doctor.sh # detect ghosts bash ~/.claude/skills/team-agents/scripts/doctor.sh --fix # auto-fix bash ~/.claude/skills/team-agents/scripts/spawn-skills.sh $T $A # create /agent skills bash ~/.claude/skills/team-agents/scripts/shutdown-skills.sh $T $A # archive to /tmp bash ~/.claude/skills/team-agents/scripts/shutdown-worktrees.sh $R # sweep worktrees

### sync

REPOROOT=$(git rev-parse --show-toplevel) for wt in "$REPOROOT/agents"/*/; do AGENT=$(basename "$wt") git -C "$wt" fetch origin main:main 2>/dev/null git -C "$wt" merge main --no-edit 2>/dev/null done

### merge

git diff --quiet HEAD 2>/dev/null || { echo "Stash first"; exit 1; } git checkout main git merge "agents/$AGENT" --no-ff -m "merge: $AGENT from team $TEAM"

---

## Base System Facts

**Provides**: mailbox (JSON + file locking), 10 structured message types, permission escalation (worker→leader→user), auto-resume on SendMessage to stopped agent, task self-claim by idle agents, deterministic IDs (`name@team`), plan auto-approval, session resume (prior-session teams persist).

**Does NOT provide** (we add): heartbeat protocol (PROGRESS/STUCK/DONE/ABORT), presence dots, ghost detection, structured task handoff.

**Architecture**: message priority shutdown>leader>peer>FIFO, structured messages cannot broadcast, two abort controllers per agent (lifecycle vs work), pane creation uses Promise-chain mutex, 50-message UI cap.

---

## Gotchas + Limitations

1. **No session resume** — `/resume` doesn't restore in-process teammates
2. **One team per session** — clean up before starting another
3. **No nested teams** — teammates can't spawn teams
4. **Lead is fixed** — no promotion or transfer
5. **Permissions at spawn** — all teammates inherit lead's mode
6. **Task status lag** — agents sometimes forget TaskUpdate
7. **Split panes** — requires tmux/iTerm2, not VS Code/Ghostty
8. **~3-7x tokens** vs single agent
9. **Same file = overwrites** — each agent must own different files
10. **Shutdown slow** — agents finish current request first
11. **Structured messages cannot broadcast** — send individually, or use `scripts/broadcast-shutdown.sh $TEAM` to auto-generate the per-agent block (#212)

---

ARGUMENTS: $ARGUMENTS