Textos tecnicos do projeto initech.
28 de marco de 2026
Por Que Construimos um Multiplexador de Terminal para Agentes de IA
Construimos uma TUI em Go que gerencia multiplos agentes Claude Code rodando em paralelo. Ela substituiu o tmux como nosso runtime de sessao.
De a cada agente um terminal rodando Claude Code com instrucoes especificas para o papel. Um agente supervisor coordena. Agentes engenheiros implementam. Um agente QA valida. Um agente shipper faz releases. Cada agente recebe um CLAUDE.md que codifica sua identidade, restricoes, fluxo de trabalho e protocolo de comunicacao.
Rodamos isso em quatro projetos antes de construir o initech. Entregou software real: engenharia paralela, QA independente, gates de release, memoria institucional entre sessoes.
O tmux quebra de tres formas que pioram conforme voce adiciona agentes.
tmux send-keys nao tem garantia de entrega. Voce envia uma mensagem para o painel de um agente e torce para que chegue. Quando nao chega, nao ha erro. Um relatorio de conclusao do eng para o super se perde, super nao sabe que eng terminou, QA nunca e acionado, e o bead fica parado por uma hora.
Um agente travado e um produtivo parecem identicos no tmux. Terminado e no meio do trabalho parecem identicos. A unica forma de saber e espiar cada painel. Com 9 agentes, sao 9 verificacoes manuais a cada 10-15 minutos.
O tmux nao sabe qual trabalho existe, quem esta atribuido a que, ou que um agente acabou de marcar uma tarefa como pronta para QA. Toda orquestracao vive na janela de contexto do supervisor. O contexto compacta. Mensagens se perdem. O agente supervisor esquece que eng terminou. A cadeia de despacho trava.
O tmux e um multiplexador de terminal de proposito geral fazendo um trabalho que precisa de inteligencia no nivel da aplicacao.
Cada sessao roda um Unix domain socket. initech send escreve texto no PTY do agente atraves do emulador, e confirma a entrega. O remetente recebe um OK explicito ou erro em segundos.
$ initech send eng1 "fix the auth bug in middleware.go" $ initech peek eng1 -n 20
Primeiro tentamos monitorar os logs de sessao JSONL. Nao era confiavel: Claude escreve no JSONL nos limites de conversacao, nao de forma previsivel. Durante uma pausa de 45 segundos para pensar, zero entradas. Qualquer timeout esta errado para algum valor de timeout.
O que funciona: rastrear quando o PTY produziu saida pela ultima vez. O spinner do Claude Code anima a 10-30 fps durante o pensamento. O unico estado com zero saida e ocioso-no-prompt. Um limiar de 2 segundos de recencia fornece deteccao binaria limpa.
Ponto verde significa trabalhando. Cinza significa ocioso. Amarelo significa ocioso com tarefas esperando. O overlay mostra o estado de cada agente sem abrir nenhum painel.
JSONL falhou para deteccao de atividade, mas funciona para eventos semanticos. Os logs de sessao contem resultados de uso de ferramentas, mensagens do assistente e sequencias de erro. O sistema de eventos faz parsing desses para:
* Conclusao de bead: agente executou bd update --status ready_for_qa
* Estagnacao: sem saida por mais de 10 minutos com um bead atribuido
* Loops de erro: 3+ falhas consecutivas de ferramentas
* Reivindicacao de beads: auto-detectada a partir dos comandos bd, sem necessidade de chamada CLI extra
Eventos aparecem como notificacoes toast. "eng1 completed ini-bhk.3" aparece em verde antes mesmo do super reportar.
A faixa de cada agente mostra seu bead atual. O overlay mostra o estado de todos os agentes num relance. Quando um agente fica ocioso apos ter um bead, a TUI avisa o agente supervisor diretamente: "[from initech] eng1 is now idle (bead: ini-bhk.3). Check if work is complete."
Cada numero acima foi produzido pela propria ferramenta. O initech gerenciou os agentes que construiram o initech.
A TUI e o runtime. Os templates sao a inteligencia. Um CLAUDE.md ruim produz saida ruim independente de quao boa a TUI seja. Reescrevemos todos os 11 templates tres vezes, cada vez codificando licoes de falhas reais: agentes engenheiros pulando comentarios de PLAN, agentes QA carimbando sem verificar, o agente supervisor fazendo trabalho em vez de despachar.
Tres abordagens antes que a recencia de bytes do PTY funcionasse. Monitoramento de JSONL: muito lento. Taxa de saida do terminal: falsos positivos de SIGWINCH. Deteccao de prompt: fragil a mudancas de UI. A abordagem do spinner so funciona porque o Claude Code sempre produz saida quando esta trabalhando. Uma tela estatica de "thinking..." quebraria isso.
A falha numero um do agente supervisor: fazer implementacao em vez de despachar. Despachar parece lento. Mas o ponto central do multi-agente e especializacao. "Nao usar agentes" agora e o primeiro modo de falha critico no template do supervisor.
Todo agente eventualmente esquece de comentar PLAN antes de codar, ou fazer push antes de marcar ready_for_qa, ou limpar a exibicao do bead. Auto-notify existe porque agentes esquecem de reportar conclusao. Guardrails ajudam mas nao eliminam isso. Conformidade com o processo e um gradiente, nao um binario.
Portabilidade de sessao nao foi iniciada. Mover uma sessao entre maquinas (MacBook para workbench) requer rsync manual. O PRD descreve um comando initech migrate que ainda nao existe.
Gerenciamento de recursos esta atras de uma flag. Auto-suspend/resume sob pressao de memoria (a funcionalidade que dobraria a capacidade efetiva de agentes num laptop de 36GB) esta implementada mas bloqueada atras de --auto-suspend porque a politica nao foi testada o suficiente em sessoes reais.
Onboarding e precario. Um novo usuario que roda initech pela primeira vez ve 7 paineis sem orientacao. Dicas na barra de status rodam na parte inferior, mas nao ha guia do operador documentando o fluxo completo. A ferramenta foi construida pelo seu proprio usuario, e isso se nota.
Adocao inicial. O initech ja foi usado em varios projetos, mas a base de usuarios ainda e pequena. Mais uso no mundo real vai revelar lacunas que o dogfooding nao encontrou.
curl -fsSL https://initech.sh/install.sh | bash mkdir myproject && cd myproject initech init initech
Codigo-fonte: github.com/nmelo/initech