3.4 Teams & Swarm - Claude Code Deep Dive

TeamCreateTool & File Structure

Um swarm e um named team de Claude agents compartilhando configuracao, tasks e infraestrutura de mailbox file-based. Requer CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

TeamCreateTool -- 5 passos sincronos

Uniqueness check: Se nome existe, generateWordSlug() substitui um nome aleatorio
Write team config: TeamFile JSON em ~/.claude/teams/<name>/config.json
Create task list: Fresh numbering comeca em 1
Update AppState: Sets appState.teamContext
Register cleanup: Shutdown hook limpa directories orfaos

~/.claude/
  teams/
    my-team/
      config.json           <- TeamFile
      permissions/
        pending/
        resolved/
  tasks/
    my-team/
      0001.json
      0002.json

Agent ID Format: agentName@teamName (ex: researcher@my-team)

Three Spawn Backends

tmux

Highest priority

Kill via kill-pane -t <paneId>. Detectado via TMUX e TMUX_PANE env vars.

iTerm2

Second priority

Kill via it2 session close. Check usa it2 session list (nao --version).

in-process

Non-interactive fallback

Abort via AbortController. Isolated via AsyncLocalStorage. Shares API client e MCP connections.

Importante: Detection usa env vars capturadas em module load time: TMUX, TMUX_PANE, TERM_PROGRAM, ITERM_SESSION_ID. Uma vez capturadas, sao imutaveis.

Mailbox Messaging System

Toda comunicacao entre agents e via file-based mailbox. Messages sao JSON files em ~/.claude/teams/<team>/inbox/<agent-name>/.

Tipo	Direcao	Proposito
plain text	any → any	Task updates, questions, results
shutdown_request	lead → teammate	Graceful shutdown signal
idle notification	teammate → lead	System-generated after every turn end
permission_request	worker → lead	Worker needs UI approval
permission_response	lead → worker	Approval/denial of tool use
mode_set_request	lead → teammate	Change teammate's permission mode

Permission Sync

Workers podem escalar permission requests para o team lead via mailbox. O leader ve o request na UI e aprova ou nega, permitindo controle centralizado de permissoes em swarms.

Worker

→

permission_request

→

Lead (UI)

→

permission_response

→

Worker

Full Lifecycle: 4 Phases

Phase 1 Setup

Lead calls TeamCreate, creates tasks, spawns teammates

Phase 2 Parallel Work

Teammates claim tasks, send progress, work in parallel

Phase 3 Shutdown

Lead sends shutdown_request, teammates approve and exit via gracefulShutdown(0)

Phase 4 Cleanup Guard

Se sessao termina sem TeamDelete, shutdown hook limpa orphaned panes e directories

Atencao: TeamDelete blocks on active members. Sempre shutdown teammates primeiro antes de deletar o team.

Key Design Invariants

Team = TaskList

TeamCreate cria um matching task directory. Sao coupled by design.

3 backends, 1 interface

tmux, iTerm2 e in-process compartilham a mesma API. Backend e transparente.

Detection em module load

Env vars lidas em import time. Imutaveis apos captura.

All messaging file-based

Excecao: leader permission bridge usa module-level setter.

Idle != dead

isActive: false significa turn ended. Teammate wakes on new message.

Session cleanup safety net

Orphaned panes e directories limpos on graceful shutdown.

📋 Resumo do Modulo

✔ Team = TaskList -- TeamCreate cria task directory junto

✔ 3 backends: tmux (highest), iTerm2, in-process

✔ Detection capturada em module load (env vars imutaveis)

✔ All messaging file-based (exceto leader permission bridge)

✔ Idle != dead: isActive:false = turn ended, wakes on message

✔ TeamDelete blocks on active members -- shutdown primeiro

✔ Session cleanup e safety net para panes e dirs orfaos

← 3.3 Coordinator Mode 3.5 Memory System →