telepty — plano de controle de sessões de agentes de IA distribuídas por várias máquinas

telepty é um plano de controle de sessões de agentes leve que permite enviar instruções remotamente e ler a tela de sessões de terminal AI CLI (claude, codex, gemini etc.) rodando em várias máquinas — a inferência e o trabalho continuam sendo feitos por cada agente como estão (data plane), e o telepty cuida apenas da camada que endereça essas sessões e garante a entrega (daemon em background baseado em PTY + ponte de sessão). Cada sessão recebe um endereço baseado em nome, e o sistema confirma até se a instrução foi realmente recebida, com suporte a macOS, Linux e Windows. Para a transmissão entre máquinas, não criei algo do zero, e sim construí em cima do já comprovado Tailscale (WireGuard) — em vez de reimplementar troca de chaves, NAT traversal e criptografia e aumentar a superfície de ataque, optei por delegar isso a uma camada validada em campo há anos. É open source sob licença MIT.

npm i -g @dmsdc-ai/aigentry-telepty && telepty daemon start  
  
# Envolve a CLI que você já usa e a transforma em uma sessão nomeada (uma vez em cada máquina)  
telepty allow --id orchestrator claude    # sessão do claude nesta máquina → "orchestrator"  
  
telepty inject "backend@100.x.y.z" "comece a refatoração do middleware de autenticação"   # envia instrução para a sessão remota  
telepty read-screen "backend@100.x.y.z"                               # verifica o andamento  
telepty broadcast "finalizem o trabalho e me enviem o status"                      # avisa todas as sessões

Contexto

Tornou-se comum desenvolver operando várias sessões de AI CLI em várias máquinas. A execução escala em paralelo conforme o número de sessões, mas a entrega entre sessões — propagação de instruções, verificação de progresso, coleta de resultados — ainda é feita manualmente, com a pessoa indo de um terminal a outro. Esta ferramenta também nasceu desse gargalo: ao rodar ao mesmo tempo três sessões de AI CLI em três máquinas, a etapa de “entrega” que leva instruções e resultados travou primeiro na pessoa, antes mesmo da execução.

Antes: alternar foco entre 3 terminais → copiar e colar instruções → repetir a verificação de progresso em cada sessão
telepty: injetar instruções e obter a tela a partir de um único terminal usando endereços nome@host

As ferramentas existentes não cobrem essa camada. tmux/SSH são ferramentas para “entrar” na sessão, então enviar e confirmar ainda continua manual, e frameworks de agentes exigem reescrever as sessões e workflows existentes do jeito deles. O objetivo do telepty é ser essa camada fina no meio — deixar as sessões já em execução como estão e levar apenas a entrega para a infraestrutura.

Arquitetura

Apontar sessões por nome — todas as sessões são chamadas como <nome-da-sessão>@<host>. Não é preciso se preocupar em qual máquina ou sistema operacional o destino está.
Separar “envio” de “recebimento” — se a sessão receptora estiver ocupada, a mensagem fica em fila (mailbox), e a confirmação é definida pelo estado de renderização do terminal no momento em que ela é realmente recebida. Não é preciso enviar e depois verificar manualmente.
As sessões continuam mesmo se o daemon reiniciar — o processo que segura a sessão (bridge) e o daemon de roteamento (daemon) são separados, então atualizar o daemon não interrompe trabalhos em andamento.
Transferência delegada a uma camada comprovada — não foi criado um protocolo P2P próprio. Se houver Tailscale, o daemon detecta automaticamente o IP da tailnet e se conecta diretamente por cima dela: 0 portas abertas, 0 gerenciamento de certificados, 0 regras de firewall. Em ambientes sem tailnet, conecta via túnel SSH (telepty connect user@host) — em ambos os casos, criptografia e identidade ficam por conta de ferramentas já comprovadas, e o telepty cuida apenas do endereçamento e da entrega das sessões sobre essa base.

Os comandos são seis: inject / read-screen / attach / send-key / broadcast / list, e como a CLI já é a própria API, dá para combinar tudo diretamente em scripts shell. E não foi feito só para pessoas usarem — o pacote inclui 9 skills para Claude Code, Codex e Gemini CLI (instaláveis com o instalador embutido), então os próprios agentes usam o telepty como ferramenta: consultam sessões, enviam instruções a agentes em outras máquinas e leem suas telas. O relay no demo abaixo mostra exatamente isso — não é uma pessoa, e sim cada LLM executando telepty inject diretamente.

Métricas iniciais de referência (medidas na build 0.6.11 — release atual 0.7.1 · incluindo latência de ida e volta da rede e overhead de inicialização do PTY)

confirmação de fila→recebimento em gated inject para sessão ocupada: Linux cerca de 487ms · Windows cerca de 1,2s — ainda estou acumulando mais medições, e o importante, mais do que o número, é que o critério de recebimento é a chegada do ACK no lado receptor, não uma aceitação HTTP.
a entrega entre máquinas nos 3 sistemas — macOS, Linux e Windows — foi verificada com o mesmo critério.

Segurança

O daemon faz bind apenas em localhost (127.0.0.1) e em IPs dedicados da tailnet — sem exposição em 0.0.0.0, não é possível alcançá-lo por port scan fora da tailnet. Só peers da tailnet são confiáveis, e a permissão de escrita no PTY não ultrapassa o escopo do usuário que possui a sessão. Desde a 0.7.1, requisições vindas do navegador são explicitamente rejeitadas — isso bloqueia o caminho pelo qual uma página visitada pelo usuário poderia acessar a sessão via API de controle localhost ou WebSocket (sem origem permitida por padrão).

Limitações

Está em beta. Ainda há edge cases de renderização específicos de cada CLI, e o Windows continua com selo beta. Como não faz emulação de terminal, read-screen retorna o fim do fluxo de saída, não uma grade de células — em TUIs com repaint frequente, o mesmo frame pode parecer repetido. Os itens conhecidos estão organizados na seção Limitations do README.

Links

GitHub: https://github.com/dmsdc-ai/aigentry-telepty
Demo no README: cena em que 3 LLMs (Grok·Codex·Claude) em 3 máquinas (macOS·Linux·Windows) executam telepty inject diretamente e fazem relay entre si — cada tela foi capturada ao vivo da TUI original da CLI com attach. Os mesmos comandos funcionam do mesmo jeito entre sessões na mesma máquina (inclui demo de relay na mesma máquina).
npm: @dmsdc-ai/aigentry-telepty (MIT, 0.7.1)

Quero saber quais soluções vocês usam para a camada de entrega ao operar várias sessões de AI CLI. Se enviarem feedback, vou incorporar.