Modo Coordinador

Claude Code tiene dos sistemas multi-agente distintos. El Modo Coordinador es un modelo hub-and-spoke donde un agente central orquesta a los workers. Team/Swarm es peer-to-peer donde cualquier integrante puede enviar mensajes a cualquier otro.

2 topologías multi-agente 4 herramientas exclusivas del coordinador 3 backends de terminal 1s intervalo de polling del buzón

i Dos sistemas distintos, no uno

El Modo Coordinador se activa con una variable de entorno y restringe el modelo principal a herramientas de orquestación. Team/Swarm se activa pasando un parámetro team_name a la herramienta Agent y usa tmux para la distribución visual y buzones de archivos para la mensajería.

Topologías

Modo Coordinador (hub-and-spoke)

Coordinador

(solo Agent, SendMessage, TaskStop)

┌────┼────┐

Worker 1 Worker 2 Worker 3

(herr. completas) (herr. completas) (herr. completas)

Se activa con CLAUDE_CODE_COORDINATOR_MODE=1. El coordinador no puede tocar el sistema de archivos directamente.

Team/Swarm (peer-to-peer)

Team Lead Integrante A

<── SendMessage ──>

└────────┬────────┘

Integrante B

Se activa pasando team_name a la herramienta Agent. Se visualiza en paneles tmux divididos.

Modo Coordinador

Activación

Requiere el feature flag COORDINATOR_MODE habilitado en la compilación, más la variable de entorno:

CLAUDE_CODE_COORDINATOR_MODE=1

Qué cambia

Aspecto	Modo normal	Modo coordinador
System prompt	Prompt estándar de Claude Code	Prompt específico de coordinador
Herramientas disponibles	Todas las ~45 herramientas	Solo Agent, SendMessage, TaskStop, SyntheticOutput
Acceso a archivos	Directo (Read, Edit, Write)	Solo a través de workers
Acceso a shell	Directo (Bash)	Solo a través de workers

Flujo de trabajo en 4 fases

Fase	Quién	Propósito
1. Investigación	Workers (en paralelo)	Explorar el código base — pueden correr en paralelo libremente
2. Síntesis	Coordinador	Leer hallazgos, escribir especificaciones con rutas y números de línea exactos
3. Implementación	Workers (uno por conjunto de archivos)	Realizar cambios según la especificación — un worker a la vez por área de archivos
4. Verificación	Workers	Comprobar que funciona — puede correr junto a la implementación en áreas distintas

Formato de resultado del worker

Los resultados del worker llegan como mensajes de rol usuario con XML:

<task-notification>
  <task-id>agent-a1b2c3</task-id>
  <status>completed</status>  <!-- completed | failed | killed -->
  <summary>Resumen breve de lo que ocurrió</summary>
  <result>Salida detallada del worker</result>
  <usage>Estadísticas de uso de tokens</usage>
</task-notification>

Decisión: continuar vs. lanzar nuevo

Situación	Acción	Razón
Worker de investigación exploró archivos que hay que editar	Continuar (SendMessage)	Ya tiene el contexto cargado
Investigación amplia pero implementación estrecha	Lanzar nuevo	No cargar contexto innecesario
Corregir un fallo	Continuar	Tiene el contexto del error
Verificar el código de otro worker	Lanzar nuevo	Visión fresca, sin sesgo
El enfoque anterior era totalmente erróneo	Lanzar nuevo	Pizarra en blanco

i Regla crítica: los workers no pueden ver la conversación del coordinador

Cada prompt del worker debe ser completamente autónomo. El coordinador debe sintetizar los hallazgos e incluir rutas de archivo, números de línea e instrucciones exactas. Nunca escribas "basándote en tus hallazgos": el worker no tiene acceso al contexto previo.

Sistema Team/Swarm

Estructura del equipo

Config del equipo

~/.claude/teams/{nombre-equipo}/config.json

Lista de tareas

~/.claude/tasks/{nombre-equipo}/

Buzones

~/.claude/teams/{nombre-equipo}/inboxes/{nombre}.json

Nombre del líder

"team-lead" (fijo)

Flujo de trabajo del equipo

El líder crea el equipo con TeamCreate

Crear tareas con las herramientas Task

Lanzar integrantes con la herramienta Agent (parámetros team_name + name)

Asignar tareas con TaskUpdate (campo owner)

Los integrantes trabajan y marcan tareas como completadas

Los integrantes se comunican via SendMessage

Apagado ordenado: SendMessage con {type: "shutdown_request"}

Limpieza con TeamDelete (solo funciona cuando no hay integrantes activos)

Tipos de integrante

En-proceso

Usa AsyncLocalStorage para contexto aislado dentro del mismo proceso. Se usa para testing y modo sin cabecera.

Tmux

Se ejecuta como proceso separado de Claude Code en un panel tmux. Cada panel tiene color de borde y título únicos.

iTerm2

Backend alternativo para iTerm2 en macOS, usando AppleScript para gestión de pestañas/divisiones.

Distribución tmux

Dentro de sesión tmux existente

Divide la ventana actual
Team lead: panel izquierdo 30%
Integrantes: panel derecho 70%
Layout: main-vertical

Fuera de tmux

Crea sesión nueva: claude-swarm
Nombre de ventana: swarm-view
Socket aislado: claude-swarm-{pid}
Layout: tiled

Herramienta SendMessage

Herramienta de doble propósito: continúa workers existentes en el Modo Coordinador y enruta mensajes entre integrantes en Team/Swarm.

En Modo Coordinador

// Continuar worker existente por ID de agente
SendMessage({
  to: "agent-a1b2c3",
  message: "Corrige el bug en auth.ts:45..."
})
// El worker reanuda con el contexto completo

En Team/Swarm

// Mensaje directo a un integrante
SendMessage({ to: "backend-dev", message: "..." })

// Difusión a todos (usar con moderación)
SendMessage({ to: "*", message: "Tests OK" })

Lógica de enrutamiento de mensajes

bridge:<id>

Sesión remota via REPL bridge

uds:<ruta>

Peer local via Unix Domain Socket

ID de agente registrado

Encolar o reanudar el agente en proceso

"*"

Difusión a todos via buzón de archivos

Nombre de integrante

Escribir en el buzón de archivos del integrante

Sistema de buzones

Mensajería basada en archivos JSON con proper-lockfile para evitar condiciones de carrera cuando varios integrantes escriben al mismo buzón simultáneamente. El hook React useInboxPoller consulta cada 1 segundo.

{
  from: string,       // Nombre del remitente
  text: string,       // Contenido del mensaje
  timestamp: number,  // Timestamp Unix
  read: boolean,      // Estado de lectura
  color?: string,     // Color del remitente (para UI)
  summary?: string    // Resumen breve
}

Los mensajes se inyectan en el contexto del integrante como XML:

<teammate-message teammate_id="frontend-dev" color="blue" summary="Encontré el bug CSS">
El problema está en src/styles/main.css línea 42. La propiedad
flex-direction está como "column" pero debería ser "row".
</teammate-message>

El poller también gestiona: solicitudes/respuestas de permisos, permisos de sandbox, solicitudes de apagado, actualizaciones de permisos del equipo, solicitudes de cambio de modo y aprobaciones de plan.

Coordinador vs Team/Swarm

Aspecto	Modo Coordinador	Team/Swarm
Topología	Hub-and-spoke	Peer-to-peer
Comunicación	Coordinador ↔ Workers solo	Cualquier integrante ↔ Cualquier integrante
Herramientas del coord.	Agent, SendMessage, TaskStop solo	Herramientas completas
Herramientas de workers	Completas (sin Agent/SendMessage)	Completas + SendMessage
Mensajería	XML task-notification	Buzones de archivos JSON
Terminal UI	Sin UI especial	Paneles tmux divididos
Activación	CLAUDE_CODE_COORDINATOR_MODE=1	Agent tool con param team_name
Ideal para	Tareas complejas que necesitan orquestación estricta	Trabajo paralelo colaborativo

→ La restricción clave que hace seguro el Modo Coordinador

El coordinador no tiene acceso al sistema de archivos. No puede leer, escribir ni ejecutar comandos. Toda acción sobre el código debe pasar por un worker. Esto convierte al coordinador en una capa puramente de razonamiento y delegación: puede planificar y orquestar sin hacer cambios accidentalmente.