C Claude Code Internals
EN | ES

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

1

El líder crea el equipo con TeamCreate

2

Crear tareas con las herramientas Task

3

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

4

Asignar tareas con TaskUpdate (campo owner)

5

Los integrantes trabajan y marcan tareas como completadas

6

Los integrantes se comunican via SendMessage

7

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

8

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.