telepty — plan de contrôle de sessions d’agents IA réparties sur plusieurs machines

telepty est un plan de contrôle léger pour sessions d’agents qui permet d’envoyer des instructions à distance et de lire l’écran de sessions de CLI IA dans un terminal (claude, codex, gemini, etc.) tournant sur plusieurs machines — le raisonnement et le travail restent effectués par chaque agent (data plane), tandis que telepty ne prend en charge que la couche qui adresse ces sessions et garantit la transmission (démon en arrière-plan basé sur PTY + pont de session). Chaque session reçoit une adresse basée sur un nom, l’outil vérifie même que l’instruction a bien été effectivement reçue, et macOS, Linux et Windows sont pris en charge. Pour le transport entre machines, nous ne l’avons pas implémenté nous-mêmes : nous l’avons construit au-dessus de Tailscale (WireGuard), déjà éprouvé. Plutôt que d’augmenter la surface d’attaque en réimplémentant l’échange de clés, la traversée NAT et le chiffrement, nous avons choisi de déléguer cela à une couche éprouvée en production depuis des années. C’est un open source sous licence MIT.

npm i -g @dmsdc-ai/aigentry-telepty && telepty daemon start  
  
# Enveloppe tel quel le CLI que vous utilisiez déjà pour en faire une session nommée (une fois sur chaque machine)  
telepty allow --id orchestrator claude    # session claude de cette machine → "orchestrator"  
  
telepty inject "backend@100.x.y.z" "인증 미들웨어 리팩터링 시작해줘"   # envoyer une instruction à une session distante  
telepty read-screen "backend@100.x.y.z"                               # vérifier l’avancement  
telepty broadcast "작업 마무리하고 상태 보고해줘"                      # annoncer à toutes les sessions

Contexte

Il est devenu courant de développer en exploitant plusieurs sessions de CLI IA sur plusieurs machines. L’exécution se met à l’échelle en parallèle avec le nombre de sessions, mais la transmission entre sessions — propagation des instructions, vérification de l’avancement, récupération des résultats — reste effectuée par une personne qui navigue entre les terminaux. C’est aussi de ce goulet d’étranglement qu’est né cet outil : en faisant tourner simultanément trois sessions de CLI IA sur trois machines, l’étape de « transmission » des instructions et des résultats s’est retrouvée bloquée par l’humain avant même l’exécution.

Avant : passer d’un terminal à l’autre entre 3 terminaux → copier-coller les instructions → répéter la vérification de l’avancement pour chaque session
telepty : injecter des instructions depuis un seul terminal via une adresse nom@hôte et récupérer l’écran

Les outils existants ne couvrent pas cette couche. tmux/SSH sont des outils pour « s’attacher » à une session, donc l’envoi et la vérification restent manuels ; les frameworks d’agents demandent de réécrire les sessions et workflows existants à leur manière. telepty vise la couche fine située entre les deux : laisser intactes les sessions déjà en cours et descendre uniquement la transmission dans l’infrastructure.

Conception

Cibler les sessions par nom — toutes les sessions sont appelées sous la forme <nom-de-session>@<hôte>. Inutile de se soucier de la machine ou de l’OS où se trouve la cible.
Distinguer « envoyé » et « reçu » — si la session réceptrice est occupée, le message est conservé dans une file (mailbox), et le moment où il est effectivement reçu est déterminé et confirmé à partir de l’état de rendu du terminal. Plus besoin pour l’humain de revérifier après l’envoi.
Les sessions survivent au redémarrage du démon — le processus qui détient la session (bridge) et le démon de routage (daemon) sont séparés, de sorte qu’une mise à niveau du démon n’interrompt pas le travail en cours.
Le transport est délégué à une couche éprouvée — nous n’avons pas créé notre propre protocole P2P. Si Tailscale est présent, le démon détecte automatiquement l’IP du tailnet et s’y connecte directement : 0 port à ouvrir, 0 certificat à gérer, 0 règle de pare-feu. Dans les environnements sans tailnet, il se connecte via un tunnel SSH (telepty connect user@host) — dans les deux cas, le chiffrement et l’identité sont pris en charge par des outils déjà éprouvés, et telepty ne gère au-dessus que l’adressage et la transmission des sessions.

Les commandes sont au nombre de six — inject / read-screen / attach / send-key / broadcast / list — et comme le CLI fait office d’API, elles peuvent être combinées directement dans des scripts shell. Et ce n’est pas conçu uniquement pour les humains : 9 skills pour Claude Code, Codex et Gemini CLI sont incluses dans le package (installables via l’installateur intégré), si bien que les agents eux-mêmes utilisent telepty comme outil : ils listent les sessions, envoient des instructions à des agents sur d’autres machines et lisent leurs écrans. Le relais de la démo ci-dessous montre exactement cela : ce ne sont pas des humains, mais chaque LLM qui exécute directement telepty inject.

Premiers indicateurs de référence (mesurés sur le build 0.6.11 — version actuelle 0.7.1 · incluant l’aller-retour réseau et le surcoût d’initialisation PTY)

Confirmation file→réception d’un gated inject vers une session occupée : environ 487 ms sous Linux · environ 1,2 s sous Windows — davantage de mesures sont en cours, et l’important n’est pas tant le chiffre que le fait que le critère de réception est l’arrivée de l’ACK côté récepteur, et non l’acceptation HTTP.
La transmission inter-machines sur les 3 OS macOS·Linux·Windows a été vérifiée selon le même critère.

Sécurité

Le démon se lie uniquement à localhost (127.0.0.1) et à l’IP dédiée du tailnet — aucune exposition sur 0.0.0.0, donc il est inaccessible par scan de ports depuis l’extérieur du tailnet. Seuls les pairs du tailnet sont considérés comme fiables, et les droits d’écriture sur le PTY ne dépassent pas le périmètre de l’utilisateur propriétaire de la session. Depuis la 0.7.1, les requêtes provenant d’un navigateur sont explicitement refusées : cela bloque le chemin par lequel une page web visitée par l’utilisateur pourrait accéder à l’API de contrôle localhost ou au WebSocket des sessions (aucune origine autorisée par défaut).

Limites

C’est une bêta. Il reste des cas limites de rendu selon les CLI, et Windows porte l’étiquette beta. Comme telepty ne fait pas d’émulation de terminal, read-screen renvoie la fin du flux de sortie plutôt qu’une grille de cellules — dans les TUI qui repeignent souvent l’écran, la même frame peut sembler se répéter. Les points connus sont récapitulés dans la section Limitations du README.

Liens

GitHub : https://github.com/dmsdc-ai/aigentry-telepty
Démo README : une scène où 3 LLM (Grok·Codex·Claude) sur 3 machines (macOS·Linux·Windows) exécutent eux-mêmes telepty inject pour se relayer mutuellement — chaque écran est une capture live de la TUI du CLI d’origine via attach. La même commande fonctionne aussi telle quelle entre sessions sur une seule machine (démo de relais sur une même machine incluse).
npm : @dmsdc-ai/aigentry-telepty (MIT, 0.7.1)

Je suis curieux de connaître les solutions de couche de transmission de celles et ceux qui exploitent plusieurs sessions de CLI IA. Vos retours seront pris en compte.