Cross-session messaging en Claude Code: sesiones que hablan
Cross-session messaging en Claude Code: mensajes entre sesiones con @nombre y SendMessage. Cómo activarlo, un caso backend-frontend real y sus límites.
Tienes dos terminales abiertas. En la izquierda, una sesión de Claude Code renombra un campo del endpoint de pedidos. En la derecha, otra sesión sigue construyendo el formulario contra el campo viejo.
Tú eres el único puente entre las dos. Copias, pegas, explicas el cambio otra vez. Si te despistas diez minutos, el frontend acaba escrito contra un contrato que ya no existe.
Claude Code tiene una función para cortar ese copia-pega: cross-session messaging. Una sesión avisa a otra sin que tú hagas de mensajero.
Este post no discute si te conviene trabajar con varios agentes. Eso ya está en cómo orquestar subagentes en Claude Code y en por qué falla el mega-prompt. Aquí va el manual de la función.
En corto: cross-session messaging deja que una sesión de Claude Code envíe texto a otra sesión tuya con las herramientas ListAgents y SendMessage. En la misma máquina viene activado desde la v2.1.224 (v2.1.234 en Windows nativo). Diriges el mensaje con @nombre, y la sesión receptora conserva sus propios permisos.
¿Qué es cross-session messaging en Claude Code?
Cross-session messaging (mensajes entre sesiones) es la función de Claude Code que permite a una sesión enviar un mensaje de texto a otra de tus sesiones en curso, en la misma máquina, en otra máquina o en la nube.
La documentación oficial (consultada en octubre de 2026) la separa de agent teams. Agent teams es un equipo con líder, lista de tareas compartida y teammates que arranca el propio Claude, y exige la variable experimental CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, según la doc de agent teams.
Esta función conecta sesiones que tú abriste por separado. Nadie las coordina. Solo se hablan.
Lo que viaja es texto que un Claude escribe para el otro, nunca el historial ni los archivos. Para mover el contexto completo, la doc te manda a reanudar la sesión.
Cómo activar los mensajes entre sesiones en Claude Code
En la misma máquina no se activa nada: viene encendido si cumples la versión mínima.
| Requisito | Versión mínima según la doc |
|---|---|
| Mensajes en macOS, Linux y WSL 2 | v2.1.224 |
| Mensajes en Windows nativo | v2.1.234 |
Mencionar la sesión con @ |
v2.1.232 |
| Aviso cuando otra sesión queda libre | v2.1.236 en ambas sesiones |
| Sesiones en otra máquina | v2.1.225 + Remote Control |
| Bedrock, Claude Platform on AWS, Foundry, Agent Platform o sin feature flags | v2.1.248 (solo misma máquina) |
Para comprobarlo, escribe /list-agents (alias /peers). Si Claude Code no reconoce el comando, tu sesión no tiene la función: empieza por claude --version. Si funciona, ves tu nombre en la primera línea y debajo las sesiones alcanzables.
/status muestra además una fila Peer address con el buzón de la sesión. Si pone unavailable, Claude Code no pudo crear el socket y te dice por qué.
Cómo se direccionan los mensajes entre sesiones
Un mensaje llega a una sesión por su nombre. Si no las nombras, Claude Code les pone uno y acabas adivinando cuál es cuál. Arráncalas con --name (o -n):
# Terminal 1
claude --name backend
# Terminal 2
claude --name frontend
Si la sesión ya está abierta, /rename frontend la renombra en caliente. Después tienes tres formas de direccionar:
- Dejar que Claude decida. Según la doc, Claude puede enviar un mensaje sin que se lo pidas, por ejemplo tras un cambio que afecta a otra sesión. Descubre el destino con
ListAgentsy envía conSendMessage. Tú no llamas a ninguna de las dos. - Pedirlo en lenguaje natural. "Explica lo que acabamos de hacer a la sesión de la API de pagos". Claude redacta el contenido.
- Mencionar con
@. Escribes@y las primeras letras, y eliges en el autocompletado. Con espacios, entre comillas:@"release notes".
Si arrancas con un --name que ya usa otra sesión viva, Claude Code renombra la tuya con una variante. Si dos sesiones vivas comparten nombre, Claude añade un identificador corto a cada fila y lo usa en la dirección. Si la mención es ambigua, te pregunta antes de enviar.
Caso práctico: el backend avisa al frontend de un cambio de contrato
La sesión backend acaba de cambiar GET /orders: el campo total pasa a ser totalCents, un entero en céntimos. En esa sesión escribes:
Avisa a @frontend de que GET /orders ya no devuelve `total`.
Ahora devuelve `totalCents` (entero, céntimos). El tipo está en
src/contracts/order.ts. Que no toque el backend.
En frontend aparece una línea tenue tipo › Message from @backend: …. Con Ctrl+O lees el texto completo. La vista previa solo recorta lo que ves tú: Claude lee el mensaje entero.
Si frontend está trabajando, Claude lee el mensaje entre dos llamadas a herramientas, sin interrumpir la que corre. Si está ociosa, Claude Code abre un turno nuevo con el mensaje.
Fíjate en la ruta del ejemplo: va sin @. Un archivo mencionado con @ en un mensaje llega como texto, sin adjunto. El receptor puede abrir la ruta con sus herramientas, sujeto a sus permisos. Si cada sesión trabaja en su propio worktree, el receptor verá la versión vieja de ese archivo hasta que hagas merge o rebase. Pide en el mensaje que lo haga, o pega el tipo nuevo en el texto.
Ahora el caso inverso. Desde frontend quieres saber cuándo termina la migración de backend sin vigilarla:
Avísame cuando la sesión backend termine lo que está haciendo
Claude se suscribe con el parámetro notify_when_idle de SendMessage. Si la suscripción va sin mensaje adjunto, no abre turno ni gasta tokens en la sesión vigilada. Si el aviso no llega en 12 horas, Claude Code cancela la suscripción y se lo dice a Claude.
El mensaje no sustituye al contrato escrito: avisa de que el contrato cambió. Es la lógica de "contrato primero" del libro de Spec-Driven Development.
Qué controla la sesión que recibe el mensaje
Un mensaje de otra sesión nunca cuenta como tu consentimiento. No aprueba permisos pendientes, no cambia la configuración ni CLAUDE.md, y un /compact dentro del texto no se ejecuta.
Lo que entra lo decide el setting crossSessionInbound: accept entrega, hold retiene con aviso y refuse descarta. Sin valor, depende de los modos de permiso: una sesión en bypassPermissions retiene los mensajes de sesiones normales y te abre un diálogo para aprobarlos. Si no respondes en cinco minutos (dialogExpiry), el mensaje se descarta.
Un worker claude -p no puede mostrar el diálogo de aprobación. Para que acepte mensajes sin vigilancia:
claude -p "corre la suite e2e y reporta" --settings '{"crossSessionInbound":"accept"}'
Cross-session messaging vs agent teams vs subagentes vs NOTES.md
Para pasar información entre trabajos en paralelo tienes cuatro opciones. Los datos salen de la doc oficial.
| Cross-session messaging | Subagentes | Agent teams | NOTES.md compartido |
|
|---|---|---|---|---|
| Quién arranca las sesiones | Tú, por separado | Claude, dentro de tu sesión | Claude, como líder | Tú |
| Activación | Activo desde v2.1.224 | Siempre disponible | Variable experimental | Ninguna |
| Qué viaja | Texto plano | El resultado al llamador | Mensajes y lista de tareas | Lo que se escriba |
| Aviso al receptor | Sí, abre turno si está ociosa | No aplica | Sí | No: hay que releer |
| Coste | Cada mensaje cuenta como un prompt | Lo que consuma cada subagente | Mayor: una instancia por teammate | Lo que lea cada sesión |
| Limitación / riesgo | Sin buzón durable; alcance de toda la máquina | Solo dentro de tu sesión | Experimental; límites al reanudar | Nadie se entera a tiempo |
Mi opinión: para dos o tres sesiones que abres tú en worktrees distintos, mandarse mensajes entre sesiones es lo más barato. No montas un equipo ni cambias tu flujo. Si necesitas que alguien reparta el trabajo, eso es agent teams. Y para que las sesiones no se pisen, tienes mi día real dirigiendo agentes en paralelo.
Límites de cross-session messaging
No hay buzón durable. Los mensajes retenidos por defecto caducan con dialogExpiry, cinco minutos salvo que lo cambies (un hold explícito no caduca, y como mucho se retienen 100 mensajes; a partir de ahí descarta los más antiguos). El receptor encola como máximo 50 mensajes aceptados. En el issue #89462, un usuario con 15 o más sesiones coordinadas pide direcciones estables y store-and-forward, porque los nombres rotan al reiniciar y algunos envíos fallan en silencio.
El alcance es la máquina, no el proyecto. ListAgents ve todas tus sesiones locales. El issue #92058 pide limitarlo al proyecto: hoy una sesión puede recibir mensajes pensados para las sesiones de otro repo. Hoy la salida es crossSessionInbound: "refuse" en los proyectos que no lo usan.
Hay fronteras que no cruza. Un contenedor y el host no se ven. Tampoco WSL 2 y Windows nativo en el mismo equipo. Las sesiones en modo bare no abren buzón.
Solo texto, con freno. Según la sección de limitaciones de la doc, hay un tope de alrededor de un millón de caracteres por mensaje en la misma máquina. Las ráfagas se rechazan en origen y los bucles entre dos sesiones se frenan solos.
Cuándo NO usarlo: si la información debe sobrevivir a la sesión, escríbela en el repo o en la spec. Un mensaje es un aviso, no documentación.
Pruébalo en cinco minutos con dos sesiones
Actualiza Claude Code, abre dos sesiones con --name y ejecuta /list-agents. Si aparecen las dos, pide a una que avise a la otra de tu último cambio. Sabrás enseguida si encaja en tu flujo.
Si quieres ver este flujo de punta a punta, de la idea al producto con Claude Code, está en el curso Construye con IA. Y revisar con contratos lo que generan esas sesiones lo trabajamos en el workshop SDD + Agentic Engineering.
Preguntas frecuentes
¿Cross-session messaging es lo mismo que agent teams?
No. Aquí conectas sesiones que abres tú, sin coordinador. Agent teams es experimental: una sesión líder crea teammates y reparte tareas. Ambas usan SendMessage, pero agent teams exige CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
¿Tengo que activar algo para que dos sesiones se manden mensajes?
En la misma máquina, no: viene activado desde la v2.1.224 en macOS, Linux y WSL 2, y desde la v2.1.234 en Windows nativo. Para otra máquina o la nube necesitas Remote Control con cuenta de claude.ai.
¿Los mensajes pasan por los servidores de Anthropic?
En la misma máquina, no: viajan por un socket por sesión, o una named pipe en Windows nativo. Hacia otra máquina o la nube, sí. Si quieres aprobar cada mensaje antes de que salga de tu equipo, pon "isolatePeerMachines": true. Te lo pide incluso en bypassPermissions.
¿Cómo dejo de recibir o enviar mensajes entre sesiones?
Para dejar de recibir, crossSessionInbound en refuse. Para dejar de enviar y listar, reglas de denegación para SendMessage y ListAgents. Denegar SendMessage también corta los mensajes a subagentes y teammates: es la misma herramienta.
¿Puede otra sesión hacer que la mía ejecute algo peligroso?
No sin pasar por tus permisos. Si actuar sobre un mensaje requiere un permiso que tu sesión no tiene, ves el mismo prompt de siempre.
Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.
¿Quieres construir con agentes en serio?
Curso «Construye con IA» con Claude Code, de la idea al producto.
Developer con más de 15 años en frontend y creador de Dominicode. Escribe sobre IA aplicada al desarrollo de software.
¿Te resultó útil este artículo?
Compártelo con tu comunidad y ayuda a otros desarrolladores.