telepty — plano de control para sesiones de agentes de IA distribuidas en varias máquinas

telepty es un plano de control de sesiones de agentes ligero que permite enviar instrucciones de forma remota y leer la pantalla de sesiones de CLI de IA en terminal (claude, codex, gemini, etc.) que corren en varias máquinas. El razonamiento y las tareas siguen siendo ejecutados por cada agente (data plane), mientras que telepty solo se encarga de la capa que permite direccionar esas sesiones y garantizar la entrega (daemon en segundo plano basado en PTY + puente de sesiones). Asigna a cada sesión una dirección basada en nombre, verifica incluso si la instrucción fue recibida realmente, y es compatible con macOS, Linux y Windows. Para la transmisión entre máquinas no construimos algo propio, sino que lo montamos sobre Tailscale (WireGuard), ya probado: en vez de aumentar la superficie de ataque implementando desde cero intercambio de claves, NAT traversal y cifrado, elegimos delegarlo en una capa probada durante años en entornos reales. Es open source con licencia MIT.

npm i -g @dmsdc-ai/aigentry-telepty && telepty daemon start  
  
# Envuelve la CLI que ya usabas tal cual y la convierte en una sesión con nombre (una vez en cada máquina)  
telepty allow --id orchestrator claude    # sesión claude de esta máquina → "orchestrator"  
  
telepty inject "backend@100.x.y.z" "Empieza a refactorizar el middleware de autenticación"   # instrucción a una sesión remota  
telepty read-screen "backend@100.x.y.z"                               # revisar el progreso  
telepty broadcast "Terminen el trabajo e informen el estado"                      # aviso a todas las sesiones

Contexto

Se volvió común desarrollar operando múltiples sesiones de CLI de IA en varias máquinas. La ejecución escala en paralelo según la cantidad de sesiones, pero la entrega entre sesiones —propagar instrucciones, revisar avances, recuperar resultados— sigue siendo algo que una persona hace yendo de una terminal a otra. Ese cuello de botella también fue el punto de partida de esta herramienta: al correr simultáneamente tres sesiones de CLI de IA en tres máquinas, la etapa de “entrega” de instrucciones y resultados se trabó en la persona antes que en la ejecución.

Antes: cambiar el foco entre 3 terminales → copiar y pegar instrucciones → repetir la revisión de avance en cada sesión
telepty: inyectar instrucciones desde una sola terminal usando direcciones nombre@host y recuperar la pantalla

Las herramientas existentes no cubren esta capa. tmux/SSH son herramientas para “conectarse” a una sesión, por lo que enviar y verificar sigue siendo manual, y los frameworks de agentes exigen reescribir las sesiones y flujos de trabajo existentes a su manera. telepty apunta a esa capa intermedia: una capa delgada que deja las sesiones ya en ejecución tal como están y baja solo la entrega a infraestructura.

Diseño

Apuntar a sesiones por nombre — Todas las sesiones se referencian como <nombre-de-sesión>@<host>. No hace falta preocuparse por en qué máquina ni en qué OS está el destino.
Distingue entre “enviado” y “recibido” — Si la sesión receptora está ocupada, guarda el mensaje en una cola (mailbox) y confirma el momento en que fue recibido realmente determinándolo por el estado de renderizado de la terminal. No hace falta que una persona vuelva a verificar después de enviarlo.
Las sesiones se mantienen aunque reinicies el daemon — El proceso que sostiene la sesión (bridge) y el daemon de enrutamiento (daemon) están separados, por lo que actualizar el daemon no interrumpe el trabajo en curso.
La transmisión se delega a una capa probada — No creamos un protocolo P2P propio. Si hay Tailscale, el daemon detecta automáticamente la IP del tailnet y se conecta directamente sobre ella: 0 apertura de puertos, 0 gestión de certificados, 0 reglas de firewall. En entornos sin tailnet se conecta mediante túnel SSH (telepty connect user@host): en ambos casos, el cifrado y la identidad quedan a cargo de herramientas ya verificadas, y telepty solo hace direccionamiento y entrega de sesiones encima de ellas.

Los comandos son seis: inject / read-screen / attach / send-key / broadcast / list. La CLI es la API, así que se pueden combinar directamente en scripts de shell. Y no está hecho solo para uso humano: el paquete incluye 9 skills para Claude Code, Codex y Gemini CLI (instalables con el instalador integrado), por lo que los propios agentes usan telepty como herramienta: consultan sesiones, envían instrucciones a agentes en otras máquinas y leen pantallas. El relay del demo de abajo es exactamente eso: no una persona, sino cada LLM ejecutando directamente telepty inject.

Métricas iniciales de referencia (medidas en build 0.6.11 — release actual 0.7.1 · incluyen ida y vuelta de red y overhead de inicialización de PTY)

Para gated inject hacia una sesión ocupada, de encolado a confirmación de recepción: Linux aprox. 487 ms · Windows aprox. 1.2 s. Seguimos acumulando más mediciones; lo importante, más que el número, es que el criterio de recepción no es una aceptación HTTP, sino la llegada del ACK del lado receptor.
Verificamos la entrega entre máquinas con 3 OS —macOS, Linux y Windows— usando el mismo criterio.

Seguridad

El daemon se enlaza solo a localhost (127.0.0.1) y a IPs exclusivas del tailnet: al no exponerse en 0.0.0.0, no se puede alcanzar desde fuera del tailnet ni siquiera mediante escaneo de puertos. Solo confía en peers del tailnet, y el permiso para escribir en la PTY no supera el alcance del usuario propietario de la sesión. Desde 0.7.1, rechaza explícitamente solicitudes provenientes del navegador: bloqueamos la vía por la cual una página web visitada por el usuario podría acceder a sesiones mediante la API de control o WebSocket de localhost (sin orígenes permitidos por defecto).

Limitaciones

Está en beta. Aún quedan edge cases de renderizado según la CLI, y Windows lleva etiqueta beta. Como no emula terminales, read-screen devuelve la parte final del flujo de salida, no una grilla de celdas; en TUIs con repintado frecuente, puede parecer que se repite el mismo frame. Los puntos conocidos están resumidos en la sección Limitations del README.

Enlaces

GitHub: https://github.com/dmsdc-ai/aigentry-telepty
Demo en el README: una escena donde 3 LLM (Grok, Codex y Claude) en 3 máquinas (macOS, Linux y Windows) ejecutan directamente telepty inject y se hacen relay entre sí; cada pantalla es una captura en vivo de la TUI original de la CLI mediante attach. El mismo comando funciona igual entre sesiones dentro de una sola máquina (también incluye demo de relay en la misma máquina).
npm: @dmsdc-ai/aigentry-telepty (MIT, 0.7.1)

Me interesa conocer las soluciones de capa de entrega de quienes operan varias sesiones de CLI de IA. Si envían feedback, lo incorporaré.