Orquestar equipos de sesiones de Claude Code

Coordine múltiples instancias de Claude Code trabajando juntas como un equipo, con tareas compartidas, mensajería entre agentes y gestión centralizada.

[!WARNING]

Los equipos de agentes son experimentales y están deshabilitados por defecto. Habilítelos configurando CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 en su settings.json o entorno. Sin esa variable, ningún equipo se configura al inicio de la sesión, no se escriben directorios de equipo, y Claude no genera ni propone compañeros de equipo. Los equipos de agentes tienen limitaciones conocidas alrededor de la reanudación de sesiones, coordinación de tareas y comportamiento de apagado.

Los equipos de agentes le permiten coordinar múltiples instancias de Claude Code trabajando juntas. Una sesión actúa como el líder del equipo, coordinando el trabajo, asignando tareas y sintetizando resultados. Los compañeros de equipo trabajan de forma independiente, cada uno en su propia ventana de contexto, y se comunican directamente entre sí. También puede hablar con cualquier compañero de equipo directamente sin pasar por el líder.

Antes de configurar un equipo, verifique si una opción más ligera hace el trabajo. Los subagentes funcionan dentro de una única sesión, y con mensajería entre sesiones Claude puede pasar hallazgos entre las sesiones que usted ejecuta por sí mismo.

Cuándo usar equipos de agentes

Los equipos de agentes son más efectivos para tareas donde la exploración paralela agrega valor real. Vea ejemplos de casos de uso para escenarios completos. Los casos de uso más sólidos son:

• Investigación y revisión: múltiples compañeros de equipo pueden investigar diferentes aspectos de un problema simultáneamente, luego compartir y desafiar los hallazgos de los demás
• Nuevos módulos o características: los compañeros de equipo pueden poseer cada uno una pieza separada sin pisarse mutuamente
• Depuración con hipótesis competidoras: los compañeros de equipo prueban diferentes teorías en paralelo y convergen en la respuesta más rápidamente
• Coordinación entre capas: cambios que abarcan frontend, backend y pruebas, cada uno propiedad de un compañero de equipo diferente

Los equipos de agentes agregan sobrecarga de coordinación y usan significativamente más tokens que una única sesión. Funcionan mejor cuando los compañeros de equipo pueden operar de forma independiente. Para tareas secuenciales, ediciones del mismo archivo o trabajo con muchas dependencias, una única sesión o subagents son más efectivos.

Comparar con subagents

Tanto los equipos de agentes como los subagents le permiten paralelizar el trabajo, pero operan de manera diferente. Para sesiones separadas que pasen mensajes entre sí sin un equipo, vea mensajería entre sesiones.

Los subagents reportan resultados al agente principal. En los equipos de agentes, los compañeros de equipo comparten una lista de tareas, reclaman trabajo y se comunican directamente entre sí.

Use subagents cuando necesite trabajadores rápidos y enfocados que reporten. Use equipos de agentes cuando los compañeros de equipo necesiten compartir hallazgos, desafiarse mutuamente y coordinarse por su cuenta.

Habilitar equipos de agentes

Los equipos de agentes están deshabilitados por defecto. Habilítelos configurando la variable de entorno CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS a 1, ya sea en su entorno de shell o a través de settings.json:

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

Habilitar equipos de agentes también cambia la delegación ordinaria. Claude puede nombrar un subagente por su cuenta, y mientras los equipos de agentes estén habilitados, un subagente que Claude nombra se inicia como un compañero de equipo, por lo que los equipos pueden formarse incluso cuando usted no solicitó uno. Para más información, consulte Cómo Claude inicia equipos de agentes; para desactivar el comportamiento, consulte Claude genera compañeros de equipo en lugar de subagentes.

Generar compañeros de equipo también requiere una sesión interactiva. En modo no interactivo con la bandera -p, incluidas las sesiones de Agent SDK, Claude no genera compañeros de equipo, y un subagente que Claude nombra se ejecuta como un subagente ordinario incluso con equipos de agentes habilitados.

Inicia tu primer equipo de agentes

Después de habilitar los equipos de agentes, describe la tarea y los compañeros de equipo que quieres en lenguaje natural. Claude los crea y coordina el trabajo según tu prompt.

Este ejemplo funciona bien porque los tres roles son independientes y pueden explorar el problema sin esperarse entre sí:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

A partir de ahí, Claude completa una lista de tareas compartida en una sesión que tiene las herramientas Task, crea compañeros de equipo para cada perspectiva, hace que exploren el problema y sintetiza los hallazgos cuando terminan.

A veces Claude puede usar subagentes en lugar de crear un equipo. Los subagentes aparecen en el mismo panel de agentes que los compañeros de equipo, así que el panel por sí solo no confirma que se haya formado un equipo. Si Claude creó subagentes en su lugar, vuelve a pedirlo y solicita explícitamente un equipo de agentes.

La terminal del líder muestra los compañeros de equipo en el panel de agentes, debajo de la entrada del prompt. Desde el panel:

• Flechas arriba y abajo: selecciona un compañero de equipo
• Enter: abre la transcripción del compañero de equipo seleccionado y envíale un mensaje directamente
• Escape: borra la selección. Mientras ves la transcripción de un compañero de equipo, Escape interrumpe el turno actual de ese compañero

La fila de un compañero de equipo inactivo permanece en el panel mientras cualquier compañero de equipo o subagente siga trabajando, así que puedes seleccionarla para revisar su transcripción o enviarle más trabajo. Una vez que todos los agentes del panel están inactivos, las filas inactivas se ocultan después de 30 segundos y reaparecen en el siguiente turno del compañero de equipo; el compañero sigue en ejecución y se le puede seguir enviando mensajes mientras está oculto.

Cuando más de tres compañeros de equipo están inactivos a la vez, las filas posteriores a las tres primeras se contraen en una sola fila que cuenta los compañeros contraídos, como 2 idle agents cuando cinco están inactivos. Selecciónala y presiona Enter para expandir las filas contraídas, o presiona Esc para volver a contraerlas. Los compañeros de equipo que están trabajando, los que fallaron y el compañero que estás viendo siempre conservan sus propias filas.

Si quieres que cada compañero de equipo esté en su propio panel dividido, consulta Elegir un modo de visualización.

Controla tu equipo de agentes

Dile al líder lo que quieres en lenguaje natural. Se encarga de la coordinación del equipo, la asignación de tareas y la delegación según tus instrucciones.

Elige un modo de visualización

Los equipos de agentes admiten dos modos de visualización:

• En proceso: todos los compañeros de equipo se ejecutan dentro de tu terminal principal. Usa las teclas de flecha arriba y abajo en el panel de agentes para seleccionar un compañero de equipo, luego presiona Enter para verlo y escribe para enviarle un mensaje directamente. Funciona en cualquier terminal, sin configuración adicional.
• Paneles divididos: cada compañero de equipo obtiene su propio panel. Puedes ver la salida de todos a la vez y hacer clic en un panel para interactuar directamente. Requiere tmux o iTerm2.

[!NOTE]

tmux tiene limitaciones conocidas en ciertos sistemas operativos y tradicionalmente funciona mejor en macOS. Usar tmux -CC en iTerm2 es el punto de entrada sugerido para tmux.

El valor predeterminado es "in-process". Establece "auto" para habilitar los paneles divididos cuando ya estés ejecutando dentro de una sesión de tmux, o cuando tu terminal sea iTerm2 con la CLI it2 instalada; de lo contrario, se recurre al modo en proceso. El ajuste "tmux" habilita el modo de paneles divididos y detecta automáticamente si usar tmux o iTerm2 según tu terminal.

Establece "iterm2" para usar explícitamente los paneles divididos nativos de iTerm2. Este modo requiere la CLI it2 y muestra un error con el comando de instalación si falta it2. La solicitud de configuración que ofrece instalar it2 o cambiar a tmux aparece con "auto" o "tmux" cuando tu terminal es iTerm2 y tmux está disponible como respaldo.

Para sobrescribir el valor predeterminado, establece teammateMode en ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Para establecer el modo en una sola sesión, pásalo como flag:

claude --teammate-mode auto

El flag --teammate-mode es experimental y no aparece en claude --help.

El modo de paneles divididos requiere tmux o iTerm2 con la CLI it2. Para instalarlos manualmente:

• tmux: instálalo mediante el gestor de paquetes de tu sistema. Consulta la wiki de tmux para ver las instrucciones específicas de cada plataforma.
• iTerm2: instala la CLI it2 y luego habilita la API de Python en iTerm2 → Settings → General → Magic → Enable Python API.

Especifica compañeros de equipo y modelos

Claude decide cuántos compañeros de equipo generar según tu tarea, o puedes especificar exactamente lo que quieres:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code elige el modelo de cada compañero de equipo a partir de la primera de estas opciones que aplique:

1. El modelo que tu prompt de generación nombra para ese compañero de equipo.
2. Para un compañero de equipo generado a partir de una definición de subagente, el model de la definición, donde inherit selecciona el modelo del líder.
3. CLAUDE_CODE_SUBAGENT_MODEL, cuando está establecida en cualquier valor distinto de inherit.
4. El modelo actual del líder.

Si un mod instalado establece un modelo en su hook agent.spawn, Claude Code usa ese modelo en lugar de la primera fuente.

Si estableces CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, las dos primeras fuentes no aplican. Claude Code elige el modelo de cada compañero de equipo a partir de CLAUDE_CODE_SUBAGENT_MODEL cuando está establecida en cualquier valor distinto de inherit, y del modelo actual del líder en caso contrario. Requiere Claude Code v2.1.257 o posterior.

Antes de v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL iba primero en este orden.

[!NOTE]

teammateDefaultModel se eliminó en v2.1.234; Claude Code ignora cualquier valor restante. En su lugar, nombra el modelo en tu prompt.

Claude Code compara el modelo que selecciona para un compañero de equipo con la lista de permitidos availableModels de tu organización. Cuando la lista de permitidos bloquea un valor, Claude Code lo sustituye por otro modelo:

• Alias de familia como opus: en la API de Anthropic y en Claude Platform on AWS, Claude Code ejecuta el compañero de equipo con la versión más reciente de esa familia que permita la lista de permitidos. En proveedores con ID de modelo específicos del proveedor, donde la sustitución no opera, un alias bloqueado recurre a la alternativa como cualquier otro valor bloqueado, según el siguiente punto
• Cualquier otro valor bloqueado, incluido un alias de familia en proveedores donde la sustitución no opera, o uno cuya familia no tiene ninguna versión permitida: Claude Code ejecuta el compañero de equipo con el modelo del líder. Si estableces CLAUDE_CODE_SUBAGENT_MODEL, Claude Code prueba primero ese modelo, bajo estas mismas reglas

De forma predeterminada, un compañero de equipo que usa el modelo del líder hereda el nivel de esfuerzo del líder. En el modo de paneles divididos esto aplica a partir de v2.1.186; las versiones anteriores no pasaban el nivel de esfuerzo de la sesión del líder a los compañeros de equipo en paneles divididos. Para un compañero de equipo que usa otro modelo, consulta Nivel de esfuerzo de subagentes y compañeros de equipo.

Haz que los compañeros de equipo planifiquen antes de implementar

Para tareas complejas o riesgosas, puedes hacer que los compañeros de equipo planifiquen antes de implementar. Un compañero de equipo que Claude genera mientras el líder está en modo plan también trabaja en modo plan hasta que su plan esté listo. Primero cambia el líder a modo plan y luego pide el compañero de equipo:

Spawn an architect teammate to refactor the authentication module.

Cuando ese compañero de equipo termina de planificar, envía una solicitud de aprobación del plan al líder. Si no has cambiado el modo de permisos de ese compañero de equipo desde que se generó, Claude Code aprueba el plan en cuanto llega la solicitud, sin que el líder lo revise. Una vez aprobado, el compañero de equipo sale del modo plan y comienza la implementación. Claude Code le pasa el modo de permisos actual del líder, o Manual si ese es el modo plan.

Si pones en modo plan a un compañero de equipo en proceso que está en ejecución presionando Shift+Tab mientras ves su sesión, el líder revisa el plan de esa ejecución en lugar de que Claude Code lo apruebe. No se te pide que lo apruebes; el líder lo aprueba o lo devuelve para su revisión.

Habla directamente con los compañeros de equipo

Cada compañero de equipo es una sesión de Claude Code completa e independiente. Puedes enviar un mensaje directamente a cualquier compañero de equipo para darle instrucciones adicionales, hacerle preguntas de seguimiento o redirigir su enfoque.

• Modo en proceso: usa las teclas de flecha arriba y abajo en el panel de agentes para seleccionar un compañero de equipo, luego presiona Enter para ver su sesión y escribe para enviarle un mensaje. Presiona x sobre un compañero de equipo seleccionado para detenerlo. Presiona Ctrl+T para mostrar u ocultar la lista de tareas.
• Modo de paneles divididos: haz clic en el panel de un compañero de equipo para interactuar directamente con su sesión. Cada compañero de equipo tiene una vista completa de su propia terminal.

Mientras ves a un compañero de equipo en proceso, el texto sin formato y los skills van a ese compañero de equipo, y los comandos integrados van a la sesión del líder, con estas salvaguardas:

• /compact, /clear y /rewind actúan sobre la conversación del líder, por lo que Claude Code te pide confirmación antes de ejecutar uno de ellos desde esta vista.
• /model y /fast establecen el modelo y el modo rápido del líder, no los del compañero de equipo, por lo que no se ejecutan desde esta vista. Un aviso te explica por qué.

El modelo y el modo rápido de un compañero de equipo quedan fijos cuando se genera.

Asigna y reclama tareas

La lista de tareas compartida coordina el trabajo en todo el equipo. El líder crea tareas y los compañeros de equipo las van completando. Las tareas tienen tres estados: pendiente, en curso y completada. Una tarea también puede depender de otras tareas y se muestra como bloqueada en la lista de tareas hasta que estas se completen. Los compañeros de equipo no reclaman por su cuenta una tarea bloqueada, pero tú o el líder aún pueden asignarla.

Los agentes sin las herramientas Task se coordinan mediante mensajes en lugar de la lista de tareas compartida.

El líder puede asignar tareas explícitamente, o los compañeros de equipo pueden reclamarlas por su cuenta:

• El líder asigna: dile al líder qué tarea darle a qué compañero de equipo
• Autorreclamación: después de terminar una tarea, un compañero de equipo toma por su cuenta la siguiente tarea sin asignar y sin bloquear

La reclamación de tareas usa bloqueo de archivos para evitar condiciones de carrera cuando varios compañeros de equipo intentan reclamar la misma tarea simultáneamente.

Cierra compañeros de equipo

Para finalizar correctamente la sesión de un compañero de equipo, refiérete a él por su nombre. Por ejemplo, con un compañero de equipo llamado researcher:

Ask the researcher teammate to shut down

El líder envía una solicitud de cierre. El compañero de equipo puede aprobarla, saliendo correctamente, o rechazarla con una explicación.

Los directorios compartidos del equipo se limpian automáticamente cuando termina la sesión, por lo que no hay un paso de limpieza aparte. Consulta Arquitectura para ver qué directorios se eliminan y cuáles permanecen en el disco.

Aplica controles de calidad con hooks

Usa hooks para aplicar reglas cuando los compañeros de equipo terminan su trabajo o cuando se crean o completan tareas:

• TeammateIdle: se ejecuta cuando un compañero de equipo está a punto de quedar inactivo. Sal con el código 2 para enviar comentarios y mantener al compañero de equipo trabajando.
• TaskCreated: se ejecuta cuando se está creando una tarea. Sal con el código 2 para impedir la creación y enviar comentarios.
• TaskCompleted: se ejecuta cuando una tarea se está marcando como completada. Sal con el código 2 para impedir que se complete y enviar comentarios.

Cómo funcionan los equipos de agentes

Esta sección cubre la arquitectura y la mecánica detrás de los equipos de agentes. Si desea comenzar a usarlos, consulte Controle su equipo de agentes arriba.

Cómo Claude inicia equipos de agentes

Para iniciar un equipo, pida a Claude compañeros de equipo. Claude lanza un compañero de equipo cuando llama a la herramienta Agent con un name mientras los equipos de agentes están habilitados, a menos que la llamada sea un fork o pase isolation en la llamada misma. Claude Code no le pide que confirme el lanzamiento.

Claude también nombra subagentes ordinarios por su cuenta para poder enviarles mensajes más tarde. Esas llamadas siguen la misma regla, por lo que los equipos pueden formarse incluso cuando no pidió uno. Si prefiere subagentes en su lugar, desactive los equipos de agentes.

Arquitectura

Un equipo de agentes consta de:

El buzón de cada agente es un archivo JSON en ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code valida cada entrada cuando lee un archivo de buzón. Las entradas que no coinciden con el formato de mensaje se reportan como errores y se eliminan del archivo; los mensajes válidos aún se entregan.

Claude Code reporta un mensaje como enviado solo cuando la escritura en el archivo de buzón del destinatario tiene éxito, ya sea que el mensaje sea texto sin formato o un mensaje de protocolo estructurado como una aprobación de plan o una solicitud de cierre. Cuando la escritura falla, por ejemplo porque el disco está lleno o el directorio de buzón no es escribible, el agente que envía recibe un error y nada se envía. Consulte No se pudo escribir en la bandeja de entrada de un compañero de equipo para los mensajes de error y los pasos de recuperación.

Claude Code gestiona las dependencias de tareas automáticamente: cuando un compañero de equipo completa una tarea de la que otras tareas dependen, desbloquea las tareas dependientes sin ninguna acción de su parte.

Los equipos y las tareas se almacenan localmente bajo un nombre derivado de la sesión. El nombre es session- seguido de los primeros ocho caracteres del ID de sesión:

• Configuración del equipo: ~/.claude/teams/{team-name}/config.json. Claude Code elimina el directorio de configuración del equipo cuando finaliza la sesión.
• Lista de tareas: ~/.claude/tasks/{team-name}/. Este directorio permanece en el disco después de que finaliza la sesión. Para cambiar cuánto tiempo lo conserva Claude Code, establece cleanupPeriodDays.

Claude Code genera ambos automáticamente al inicio de la sesión y los actualiza a medida que los compañeros de equipo se unen, se quedan inactivos o se van.

La configuración del equipo contiene estado de tiempo de ejecución como IDs de sesión e IDs de panel tmux, por lo que no la edite manualmente ni la cree previamente: sus cambios se sobrescriben en la siguiente actualización de estado.

Para definir roles de compañeros de equipo reutilizables, use definiciones de subagentes en su lugar.

La configuración del equipo contiene un array members con el nombre y el ID de agente de cada miembro. La entrada del líder siempre lleva el tipo de agente team-lead. La entrada de un compañero de equipo lleva el tipo de agente que el líder nombró al generarlo, ya sea un tipo integrado o una definición de subagente, y omite el campo cuando el líder no nombró ninguno. Los compañeros de equipo pueden leer este archivo para descubrir otros miembros del equipo.

No hay equivalente a nivel de proyecto de la configuración del equipo. Un archivo como .claude/teams/teams.json en el directorio de su proyecto no se reconoce como configuración; Claude lo trata como un archivo ordinario.

Usar definiciones de subagentes para compañeros de equipo

Al generar un compañero de equipo en cualquier modo de visualización, puedes hacer referencia a un tipo de subagente del alcance de subagente de proyecto, usuario, administrado o de plugin. Esto te permite definir un rol una vez, como un security-reviewer o test-runner, y reutilizarlo tanto como un subagente delegado como un compañero de equipo de equipo de agentes.

Para usar una definición de subagente, nómbrela cuando pida a Claude que genere el compañero de equipo:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Claude Code lee la definición de subagente que nombró y aplica estas partes a ella al compañero de equipo. Donde una parte depende del modo de visualización del compañero de equipo, la entrada lo dice:

• tools: Claude Code limita el compañero de equipo a las herramientas en la lista tools de la definición. Para un compañero de equipo en proceso, Claude Code agrega SendMessage a esa lista, y en una sesión que tiene las herramientas Task también agrega TaskCreate, TaskGet, TaskList y TaskUpdate.
• model: Claude Code usa el model de la definición en cualquier modo de visualización cuando su solicitud de generación no nombra uno. Consulte cómo Claude Code elige el modelo de un compañero de equipo.
• disallowedTools: para un compañero de equipo en proceso, Claude Code quita del conjunto del compañero de equipo las herramientas en el disallowedTools de la definición. SendMessage y las herramientas Task que agrega siguen disponibles incluso cuando la lista las nombra.
• effort: para un compañero de equipo en proceso, Claude Code aplica el effort de la definición según las reglas de esfuerzo del frontmatter.
• autoCompactWindow: para un compañero de equipo en proceso, Claude Code aplica el autoCompactWindow de la definición según las reglas de ese campo. Un compañero de equipo de panel dividido ignora el campo. Requiere Claude Code v2.1.296 o posterior.
• Body: para un compañero de equipo en proceso, Claude Code agrega el cuerpo de la definición a su solicitud de sistema predeterminada como instrucciones adicionales. Para un compañero de equipo de panel dividido, Claude Code usa el cuerpo en lugar de su solicitud de sistema predeterminada.
• skills: Claude Code no aplica los skills de la definición a un compañero de equipo en ningún modo de visualización. El compañero de equipo carga skills de su configuración de proyecto y usuario.
• mcpServers: para un compañero de equipo de panel dividido, Claude Code aplica el mcpServers de la definición bajo las reglas para ese campo, que cubren una sesión iniciada con --agent también. Un compañero de equipo en proceso ignora el campo y carga servidores MCP de su configuración de proyecto y usuario.

Cuando Claude envía un mensaje a un compañero de equipo en proceso que ya no se está ejecutando, Claude Code lo trae de vuelta en la misma sesión, restaura cualquier conversación guardada para él, y le da el mensaje como su siguiente solicitud. Después de reanudar una sesión, los compañeros de equipo no se traen de vuelta de esta manera, según la limitación de reanudación.

Para un compañero de equipo que trae de vuelta, Claude Code vuelve a aplicar una definición que provino del directorio .claude/agents/ de un proyecto o un directorio --add-dir solo si ha confiado en la carpeta en la que se encuentra el archivo del agente. Confiar en una carpeta principal no cuenta. Hasta entonces, el compañero de equipo vuelve sin ninguna de las herramientas o instrucciones de la definición, manteniendo solo las herramientas que Claude Code agrega a cada compañero de equipo en proceso. Consulte la definición del agente del compañero de equipo no fue restaurada para el texto del aviso.

Permisos

Para alternar el modo de permisos de un compañero de equipo en ejecución, presiona Shift+Tab, aunque un compañero de equipo en proceso puede ejecutarse en el modo del líder en su lugar. Para un compañero de equipo de panel dividido, presiónalo en su panel. Para un compañero de equipo en proceso, presiónalo mientras ves su sesión, y el compañero de equipo comprueba su modo cuando inicia su siguiente turno.

[!NOTE]

Un compañero de equipo en proceso que no está en modo plan se ejecuta en el modo del líder mientras el líder está en el modo acceptEdits, auto o bypassPermissions. Cambiar el compañero de equipo a Manual no cambia eso, aunque su barra de estado muestre Manual.

Para que pida confirmación antes de editar, presiona Enter en la fila main del panel de agentes y cambia también el líder al modo Manual. Entonces el líder también pide confirmación, al igual que cualquier otro compañero de equipo en modo Manual.

No puedes establecer modos de permisos por compañero de equipo en el momento de la generación. Un nuevo compañero de equipo comienza con el modo del líder, incluido el modo bypassPermissions, que se activa con --dangerously-skip-permissions. Si el líder está en el modo dontAsk, el compañero de equipo comienza en modo Manual en su lugar.

Un compañero de equipo en proceso se ejecuta bajo las reglas de permitir y denegar activas del líder, por lo que --disallowedTools, --tools y --allowedTools se aplican a él. Para un compañero de equipo de panel dividido, revisa cada flag:

• --disallowedTools y --tools: el compañero de equipo comienza con las reglas de denegación de línea de comandos y la lista de herramientas del líder. Requiere Claude Code v2.1.309 o posterior.
• --allowedTools: Claude Code no pasa este flag a un compañero de equipo de panel dividido, por lo que una acción que permitiste solo con él no está aprobada previamente allí. Para aprobar esas acciones de antemano, coloca las reglas bajo permissions.allow en --settings cuando inicies el líder. Por ejemplo, ejecuta claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' en tu shell. Las reglas se aplican al líder y a cada compañero de equipo de panel dividido durante esa sesión.

Las solicitudes de permiso de los compañeros de equipo aparecen en la sesión del líder, así que apruébalas allí tú mismo. No necesitas aprobar el plan de un compañero de equipo.

Mensajes entre agentes

Cuando un agente envía a otro un mensaje sobre SendMessage, Claude Code le dice al agente receptor que el mensaje provino de otra sesión de Claude, no de usted. Un compañero de equipo no puede aprobar un aviso de permiso o proporcionar consentimiento en su nombre, y un compañero de equipo al que se le negó una acción no puede retransmitirla a otro compañero de equipo para eludir la verificación. Las mismas reglas se aplican a un mensaje que llega de una de sus otras sesiones de Claude Code, fuera del equipo completamente.

En modo auto, el clasificador aplica dos verificaciones a los mensajes entre agentes:

• Trata una afirmación de aprobación retransmitida de otro agente como entrada no confiable en lugar de confirmación de usted.
• Revisa cada mensaje antes de que Claude Code lo entregue, ya sea un mensaje simple o un mensaje de protocolo estructurado como una solicitud de cierre o una respuesta de aprobación de plan. Un mensaje que bloquea nunca llega al destinatario.

Contexto y comunicación

Cada compañero de equipo tiene su propia ventana de contexto. Cuando se genera, un compañero de equipo carga el mismo contexto de proyecto que una sesión regular: CLAUDE.md, servidores MCP y skills. Si inicia el líder con --setting-sources, los compañeros de equipo cargan desde la misma lista restringida de fuentes. Antes de v2.1.281, los compañeros de equipo de panel dividido cargaban cada fuente de configuración.

Un compañero de equipo también recibe la solicitud de generación del líder. El historial de conversación del líder no se transfiere.

Cómo los compañeros de equipo comparten información:

• Entrega automática de mensajes: cuando los compañeros de equipo envían mensajes, se entregan automáticamente a los destinatarios. El líder no necesita sondear actualizaciones.
• Notificaciones de inactividad: cuando un compañero de equipo termina y se detiene, notifica automáticamente al líder e incluye su respuesta final en la notificación. Un compañero de equipo cuyo turno termina en un error de API notifica al líder que falló e incluye el texto del error.
• Lista de tareas compartida: agentes que tienen las herramientas Task pueden ver el estado de la tarea y reclamar trabajo disponible.
• Mensajería de compañero de equipo: envíe un mensaje a un compañero de equipo específico por nombre. Para llegar a todos, envíe un mensaje por destinatario.

El líder asigna a cada compañero de equipo un nombre cuando los genera, y cualquier compañero de equipo puede enviar un mensaje a cualquier otro por ese nombre. Para obtener nombres predecibles que pueda referenciar en solicitudes posteriores, dígale al líder cómo llamar a cada compañero de equipo en su instrucción de generación.

Uso de tokens

Los equipos de agentes usan significativamente más tokens que una sesión única. Cada compañero de equipo tiene su propia ventana de contexto, y el uso de tokens se escala con el número de compañeros de equipo activos. Para investigación, revisión y trabajo de nuevas características, los tokens adicionales generalmente valen la pena. Para tareas rutinarias, una sesión única es más rentable. Consulte costos de tokens de equipo de agentes para orientación de uso.

Las solicitudes de un compañero de equipo en proceso caen fuera del bucket TTL de cache de la conversación principal, por lo que su cache se mantiene durante cinco minutos por defecto, incluso en una suscripción de Claude. Para mantenerlo durante una hora, establezca subagentPromptCacheTtl en 1h. La API factura escrituras de cache de una hora a una tasa más alta.

Ejemplos de casos de uso

Estos ejemplos muestran cómo los equipos de agentes manejan tareas donde la exploración paralela agrega valor.

Ejecutar una revisión de código paralela

Un único revisor tiende a gravitar hacia un tipo de problema a la vez. Dividir criterios de revisión en dominios independientes significa que la seguridad, el rendimiento y la cobertura de pruebas reciben atención exhaustiva simultáneamente. La indicación asigna a cada compañero de equipo una lente distinta para que no se superpongan:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Cada revisor trabaja desde la misma PR pero aplica un filtro diferente. El líder sintetiza hallazgos en los tres después de que terminen.

Investigar con hipótesis competidoras

Cuando la causa raíz es poco clara, un único agente tiende a encontrar una explicación plausible y dejar de buscar. La indicación lucha contra esto haciendo que los compañeros de equipo sean explícitamente adversarios: el trabajo de cada uno no es solo investigar su propia teoría sino desafiar las de los demás.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

La estructura de debate es el mecanismo clave aquí. La investigación secuencial sufre de anclaje: una vez que se explora una teoría, la investigación posterior está sesgada hacia ella.

Con múltiples investigadores independientes intentando activamente refutar mutuamente, la teoría que sobrevive es mucho más probable que sea la causa raíz real.

Mejores prácticas

Dé a los compañeros de equipo suficiente contexto

Los compañeros de equipo cargan contexto de proyecto automáticamente, incluyendo CLAUDE.md, MCP servers y skills, pero no heredan el historial de conversación del líder. Vea Contexto y comunicación para detalles. Incluya detalles específicos de la tarea en la indicación de generación:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Elegir un tamaño de equipo apropiado

No hay límite duro en el número de compañeros de equipo, pero se aplican restricciones prácticas:

• Los costos de tokens escalan linealmente: cada compañero de equipo tiene su propia ventana de contexto y consume tokens independientemente. Vea costos de tokens de equipos de agentes para detalles.
• La sobrecarga de coordinación aumenta: más compañeros de equipo significa más comunicación, coordinación de tareas y potencial para conflictos
• Rendimientos decrecientes: más allá de cierto punto, compañeros de equipo adicionales no aceleran el trabajo proporcionalmente

Comience con 3-5 compañeros de equipo para la mayoría de flujos de trabajo. Esto equilibra el trabajo paralelo con coordinación manejable. Si tiene 15 tareas independientes, 3 compañeros de equipo es un buen punto de partida.

Escale solo cuando el trabajo se beneficie de tener compañeros de equipo trabajando simultáneamente. Tres compañeros de equipo enfocados a menudo superan a cinco dispersos.

Dimensionar tareas apropiadamente

• Demasiado pequeñas: la sobrecarga de coordinación excede el beneficio
• Demasiado grandes: los compañeros de equipo trabajan demasiado tiempo sin check-ins, aumentando el riesgo de esfuerzo desperdiciado
• Justo bien: unidades auto-contenidas que producen un entregable claro, como una función, un archivo de prueba o una revisión

[!TIP]

El líder divide el trabajo en tareas y las asigna a los compañeros de equipo automáticamente. Si no está creando suficientes tareas, pídele que divida el trabajo en piezas más pequeñas. Tener 5-6 tareas por compañero de equipo mantiene a todos productivos y permite al líder reasignar trabajo si alguien se queda atrapado.

Espere a que los compañeros de equipo terminen

A veces el líder comienza a implementar tareas por sí mismo en lugar de esperar a los compañeros de equipo. Si nota esto:

Wait for your teammates to complete their tasks before proceeding

Comience con investigación y revisión

Si es nuevo en equipos de agentes, comience con tareas que tengan límites claros y no requieran escribir código: revisar una PR, investigar una biblioteca o investigar un error. Estas tareas muestran el valor de la exploración paralela sin los desafíos de coordinación que vienen con la implementación paralela.

Evitar conflictos de archivos

Dos compañeros de equipo editando el mismo archivo lleva a sobrescrituras. Divida el trabajo para que cada compañero de equipo posea un conjunto diferente de archivos.

Monitorear y dirigir

Verifique el progreso de los compañeros de equipo, redirija enfoques que no estén funcionando y sintetice hallazgos a medida que lleguen. Dejar que un equipo se ejecute desatendido durante demasiado tiempo aumenta el riesgo de esfuerzo desperdiciado.

Solución de problemas

Los compañeros de equipo no aparecen

Si los compañeros de equipo no aparecen después de pedirle a Claude que los genere:

• En el modo en proceso, los compañeros de equipo aparecen en el panel de agentes debajo del campo de entrada del prompt. Usa las teclas de flecha arriba y abajo para seleccionar uno y luego presiona Enter para verlo.
• Una fila de compañero de equipo que desapareció después de permanecer inactiva se ocultó, no se detuvo. Las filas inactivas se ocultan 30 segundos después de que todo el panel queda inactivo y vuelven a aparecer en el siguiente turno del compañero de equipo. Cuando hay más de tres compañeros de equipo inactivos, sus filas excedentes se contraen en una sola fila N idle agents que Enter expande. Envía un mensaje al compañero de equipo por su nombre para que una fila oculta vuelva a aparecer.
• Verifica que la tarea que le diste a Claude fuera lo suficientemente compleja como para justificar un equipo. Claude decide si genera compañeros de equipo en función de la tarea.
• Si solicitaste explícitamente paneles divididos, asegúrate de que tmux esté instalado y disponible en tu PATH:

  which tmux
  

• Para iTerm2, verifica que la CLI it2 esté instalada y que la Python API esté habilitada en las preferencias de iTerm2.

Claude genera compañeros de equipo en lugar de subagentes

Mientras los equipos de agentes están habilitados, un subagente al que Claude asigna un nombre en la sesión del líder se inicia como compañero de equipo. Claude puede asignar nombres a los subagentes por su cuenta, así que esto puede ocurrir durante una delegación que nunca planteaste como trabajo en equipo.

Para que los subagentes con nombre vuelvan a iniciarse como subagentes, desactiva los equipos de agentes estableciendo CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS en 0:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

No necesitas iniciar una nueva sesión: Claude Code vuelve a aplicar los valores env del archivo de configuración a la sesión en ejecución cuando guardas, y vuelve a leer la variable cada vez que Claude genera un subagente, así que el siguiente subagente al que Claude asigne un nombre se inicia como subagente.

Establecer la variable en 0 en tu settings.json de usuario sobrescribe una exportación del shell. Otras fuentes de configuración todavía pueden habilitar los equipos de agentes:

• Archivos de configuración con mayor precedencia: la configuración del proyecto, la configuración local y un payload de --settings se aplican después de la configuración de usuario, así que una entrada env que establezca la variable en 1 en cualquiera de ellos prevalece. Consulta Precedencia de la configuración.
• Configuración administrada: la configuración administrada se aplica después de todas las demás fuentes. Si tu organización habilita los equipos de agentes ahí, pídele a tu administrador que cambie el valor administrado.

Después del cambio, Claude todavía puede asignar nombres a los subagentes, y el nombre sigue funcionando como dirección de SendMessage. Claude recibe el resultado de cada subagente cuando termina.

Demasiadas solicitudes de permiso

Las solicitudes de permiso de los compañeros de equipo se transmiten al líder, lo que puede generar fricción. Aprueba previamente las operaciones comunes en tu configuración de permisos antes de generar compañeros de equipo para reducir las interrupciones.

Los agentes se detienen antes de tiempo

Los compañeros de equipo pueden detenerse después de encontrar errores en lugar de recuperarse. Revisa su salida seleccionando al compañero de equipo en el panel de agentes y presionando Enter en el modo en proceso, o haciendo clic en el panel en el modo dividido, y luego:

• Dales instrucciones adicionales directamente
• Genera un compañero de equipo de reemplazo para continuar el trabajo

Un mensaje del líder o de otro compañero de equipo despierta a un compañero de equipo en proceso que está esperando para reintentar una solicitud de API fallida, de modo que reintenta de inmediato en lugar de esperar todo el tiempo de reintento.

El líder también puede detenerse antes de tiempo y decidir que el equipo terminó antes de que todas las tareas estén realmente completas. Si eso ocurre, dile que continúe.

Sesiones de tmux huérfanas

Si una sesión de tmux persiste después de que termina la sesión de Claude Code, es posible que no se haya limpiado por completo. Lista las sesiones y termina la que creó el equipo:

tmux ls
tmux kill-session -t <session-name>

Limitaciones

Los equipos de agentes son experimentales. Las limitaciones actuales a tener en cuenta:

• Sin reanudación de sesión con compañeros de equipo en proceso: /resume y /rewind no restauran compañeros de equipo en proceso. Después de reanudar una sesión, el líder puede intentar enviar mensajes a compañeros de equipo que ya no existen. Si esto sucede, dígale al líder que genere nuevos compañeros de equipo.
• El estado de la tarea puede retrasarse: los compañeros de equipo a veces no marcan las tareas como completadas, lo que bloquea tareas dependientes. Si una tarea parece atrapada, verifique si el trabajo está realmente hecho y actualice el estado de la tarea manualmente o dígale al líder que empuje al compañero de equipo.
• El apagado puede ser lento: los compañeros de equipo terminan su solicitud actual o llamada de herramienta antes de apagarse, lo que puede tomar tiempo.
• Un equipo por sesión: una sesión tiene exactamente un equipo, limitado a esa sesión. No puede crear equipos nombrados adicionales ni compartir un equipo entre sesiones.
• Sin equipos anidados: los compañeros de equipo no pueden generar sus propios compañeros de equipo. Solo el líder puede gestionar el equipo.
• Sin subagentes en segundo plano desde compañeros de equipo en proceso: los propios subagentes de un compañero de equipo en proceso se ejecutan en primer plano, porque el trabajo en segundo plano de un compañero de equipo no puede sobrevivir al proceso del líder. Claude Code devuelve un error cuando un compañero de equipo genera un subagente cuya definición establece background: true. Una solicitud run_in_background: true de un compañero de equipo también falla, ya sea con un error o ejecutándose silenciosamente en primer plano. Los subagentes lanzados desde la conversación principal siguen el valor predeterminado de segundo plano.
• El líder es fijo: la sesión principal es el líder de por vida. No puede promover un compañero de equipo a líder ni transferir liderazgo.
• Sin modos de permisos por compañero de equipo en la generación: los compañeros de equipo comienzan con el modo de permisos descrito en Permisos.
• Los paneles divididos requieren tmux o iTerm2: el modo en proceso predeterminado funciona en cualquier terminal. El modo de panel dividido no es compatible con la terminal integrada de VS Code, Windows Terminal o Ghostty.

Próximos pasos

Explore enfoques relacionados para trabajo paralelo y delegación:

• Delegación ligera: subagents generan agentes auxiliares para investigación o verificación dentro de su sesión, mejor para tareas que no necesitan coordinación entre agentes
• Mensajería entre sus propias sesiones: mensajería entre sesiones permite que Claude transmita hallazgos entre las sesiones que usted ejecuta
• Sesiones paralelas manuales: Git worktrees le permiten ejecutar múltiples sesiones de Claude Code usted mismo sin coordinación de equipo automatizada