hydra-ensemble

Um app desktop multiplataforma que roda sessões de agentes de programação em paralelo, cada uma com seu próprio PTY, git worktree e diretório de configuração.

TypeScript · Tauripersonalcódigo aberto (MIT)Stack Tauri v2, Rust, React, TypeScriptLicença MITPlataformas Linux, Windows, macOSTerminal xterm.js sobre portable-ptygithub.com/javabetatester/hydra-ensemble

Visão geral

O hydra ensemble é um terminal desktop para rodar vários agentes de programação lado a lado. Cada sessão é um PTY real executando a CLI de um provedor (claude, codex, copilot, cursor, grok), geralmente dentro do seu próprio git worktree, com seu próprio diretório de configuração.

O problema que ele resolve é a colisão. Dois agentes no mesmo checkout sobrescrevem os arquivos um do outro, e duas sessões que compartilham um diretório de configuração compartilham logins, locks e históricos JSONL. O Hydra dá a cada sessão uma branch e um diretório de configuração próprios, então o trabalho em paralelo continua separável.

Além disso, ele observa cada sessão. Classifica o stream do PTY num estado ao vivo, acompanha a transcrição JSONL da CLI para obter tokens e custo, e mostra o resultado como uma pílula de status por sessão. Também traz um editor CodeMirror 6 com LSP, um kit de comandos de um clique, um terminal rápido flutuante e um inspetor de PR.

ÁreaO que faz
Terminalxterm.js com várias abas, ANSI, true color, mouse e redimensionamento
IsolamentoUm git worktree e um diretório de configuração de provedor por sessão
Statusthinking, generating, idle, needs-attention a partir do stream do PTY
CustoDados de tokens e custo lidos da transcrição JSONL da CLI
EditorCodeMirror 6 com diagnósticos LSP, hover, autocomplete e formatação
Inspetor de PRLista e mostra o diff dos PRs abertos do GitHub pela CLI gh

Instalar e rodar

Os releases trazem um .deb ou AppImage no Linux, um .exe NSIS no Windows e um .dmg no macOS. Para compilar do código-fonte você precisa de um toolchain estável do Rust, Node 22 como ferramenta de build do renderer, npm e git. Node não é uma dependência de runtime: o app distribuído é um binário nativo do Tauri.

Pré-requisitos de build no Linux (Debian/Ubuntu)bash
sudo apt-get install libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev patchelf
Rodar a partir do código-fontebash
git clone https://github.com/javabetatester/hydra-ensemble.git
cd hydra-ensemble
nvm use
npm install
npm run tauri:dev
Build de produção e o pacote do Archbash
npm run tauri:build
./scripts/install-arch.sh

Os instaladores ficam em src-tauri/target/release/bundle/. No Arch o script gera um .pkg.tar.zst nativo em dist/arch/ e o instala, no sistema todo com --system ou em ~/.local sem sudo.

RequisitoNecessário para
Claude Code (ou outra CLI de provedor) no PATHRodar sessões
gh, instalado e autenticadoInspetor de PR
typescript-language-server, gopls, pyright-langserver, rust-analyzerLSP do editor por linguagem; realce simples caso contrário
WebView2 RuntimeWindows; já vem no 11, incluído no instalador no 10
ConfiguraçãoEfeito
HYDRA_USER_DATASubstitui o diretório de dados do usuário, incluindo keybindings.json
~/.hydra-ensemble/keybindings.jsonAtalhos do usuário; um comando que começa com - remove um atalho
sentinela portable.txt ou data/Redireciona as raízes de sessões e contas para junto do binário
HYDRA_MCP=1Ativa o plano de controle MCP
Quality gatesbash
npm run typecheck
npm run lint
npm test
npm run build
cd src-tauri && cargo check

Arquitetura

ptybranch aptybranch bptybranch c
Cada sessão é um terminal ligado ao seu próprio PTY e à sua própria branch de worktree.

Um núcleo Rust é dono de processos, arquivos e git. Um renderer React no WebView da plataforma é dono da UI. Eles se encontram num único módulo, src/renderer/tauri-api, o único lugar que importa @tauri-apps/*.

text
WebView (React + zustand)
  views -> stores -> tauri-api (invoke / listen / Channel)
                          |
 Tauri core (Rust, src-tauri/src)
  commands + events (generate_handler! in lib.rs)
   |-- pty/        portable-pty, scrollback, coalescer
   |-- analyzer/   PTY stream -> session state
   |-- claude/     JSONL watcher, transcript parser
   |-- session/    lifecycle, config isolation, binding
   |-- git/        worktrees, status, diff, remote
   |-- accounts/   per-account config dirs
   '-- forge/      PR data via gh
                          |
   agent CLI in a worktree, own config dir, writes JSONL
  • Cada comando do Tauri vive no seu módulo de domínio e precisa ser registrado na lista generate_handler! em lib.rs.
  • Streams quentes (dados do pty, mensagens LSP) usam um Channel por label de janela; os demais eventos usam AppHandle::emit.
  • O estado da sessão tem duas fontes: o analisador do PTY e o watcher de JSONL, que é o autoritativo.
  • Os contratos TypeScript compartilhados ficam em src/shared e são espelhados por structs serde camelCase em Rust.
  • Segredos passam pelo chaveiro do SO (crate keyring) e nunca chegam ao renderer.

Ciclo de vida de uma sessão

  1. 1Worktreegit_create_worktree roda git worktree add -b <name> em <repo>/.hydra-ensemble/worktrees/, a partir da branch padrão informada ou detectada. Se a branch já existe, tenta de novo sem -b.
  2. 2Isolamento de configuraçãocreate_isolated_session escreve ~/.hydra-ensemble/sessions/<id>/meta.json e escolhe um diretório de configuração: primeiro uma conta salva, depois um diretório novo por sessão e, por fim, o login do host.
  3. 3SpawnPtyManager::spawn inicia a CLI do provedor num par portable-pty com um ambiente saneado e a variável do diretório de configuração exportada na linha de lançamento.
  4. 4StreamA saída do leitor é decodificada, coalescida e enviada à janela por um Channel; o mesmo texto alimenta o analisador.
  5. 5AcompanhamentoO analisador emite session:state; o watcher de JSONL resolve a transcrição e emite o estado autoritativo, os tokens e o custo.
  6. 6EncerramentoKill descarta o scrollback; destroy_isolated_session remove o diretório da sessão; git_remove_worktree roda git worktree remove --force.

Detecção de estado

ptyjsonlthinkinggeneratingidleattention
O analisador lê o texto do PTY e acende uma lâmpada por sessão; o livro-razão JSONL a sobrescreve.

PtyStreamAnalyzer lê o final da saída sem ANSI e compara a posição mais recente de quatro famílias de frases: working, thinking, idle e attention. As famílias são por provedor (AnalyzerProfileId: Claude, Cursor, Grok, Generic). Para o Claude, working é por exemplo "esc to interrupt".

  • Os estados são SessionState: idle, thinking, generating, userInput, needsAttention.
  • A análise é limitada por frame em THROTTLE_MS = 80 e olha uma janela de texto recente de 8000 caracteres.
  • Uma marca de submit dura 8 s (SUBMIT_MARK_TTL_MS) e no máximo 45 s.
  • classify_pty_failure lê o mesmo trecho final para detectar falhas de recusa, cota e login.

A saída do analisador sozinha pode travar num estado errado, por isso o watcher de JSONL a sobrescreve. AnalyzerManager roda um watchdog a cada 2 s. Um estado autoritativo travado há mais de 8 s (AUTHORITATIVE_STALE_MS) junto com um estado working é reavaliado, o que recupera sessões que pararam de escrever.

Streaming do PTY

O coalescer existe por causa de uma medição registrada no código (spike F00.2): o custo do tauri::ipc::Channel é a contagem de mensagens, não os bytes. Pedaços de 2 KB em alta taxa congelaram o WebKitGTK a 0,4 a 0,7 FPS, enquanto o mesmo volume em mensagens de 32 KB rodou fluido a 165 MB/s.

ConstanteValorPapel
WINDOW12 msDescarrega até um buffer pequeno para as teclas continuarem interativas
FLUSH_BYTES32 KBDescarga por tamanho; limita a memória
CHANNEL_CAPACITY256Fila do leitor para o coalescer; cada item é no máximo um pedaço de 64 KiB
SCROLLBACK_CAP_BYTES4 MiBAnel de replay por sessão

O backpressure é o canal limitado: quando o consumidor trava, o leitor bloqueia, o buffer do PTY no kernel enche e o processo filho desacelera. A janela começa no primeiro byte e não é reiniciada por pedaços posteriores, então a latência é limitada por WINDOW.

PtyScrollback atribui um seq monotônico a cada pedaço. Um snapshot carrega seu seq e o renderer descarta pedaços ao vivo com seq <= snapSeq, de modo que nenhum byte de fronteira é escrito duas vezes: um byte duplicado dentro de uma sequência de escape ANSI corrompe o frame. Um respawn reinicia o anel e o seq volta a 0.

pty/env.rs remove LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, as variáveis de injeção DYLD_* e NODE_OPTIONS de todo ambiente lançado.

JSONL e custo

opussonnethaikujsonlcost
O watcher acompanha o livro-razão JSONL e precifica os tokens pela tarifa do modelo no medidor de custo.

JsonlWatcher acompanha o <uuid>.jsonl do Claude, acumulando tokens, custo e contexto, e deriva o estado do turno, o nome da sessão da CLI e o id de retomada. Um lançamento passa --session-id <uuid>, então resolver o arquivo é uma busca direta; uma varredura por recência é o fallback depois de uma janela.

  • Cadências: RESOLVE_POLL 3000 ms, TAIL_POLL 5000 ms, com notify como sinal principal.
  • Re-pin: /clear e --fork-session criam um novo jsonl no mesmo diretório de projeto. O re-pin exige evidência de session::binding::arbitrate (linhagem de fork ou um /clear digitado em 30 s); uma sessão externa mais nova nunca é adotada.
  • Claims: um mapa compartilhado de uuid para sessão impede que duas sessões no mesmo cwd adotem o mesmo arquivo.
  • Catch-up seguro: ao anexar ou fazer re-pin, estados working derivados de linhas antigas não são emitidos, então um arquivo que terminou em um tool_use não consegue travar Generating numa sessão parada.
ModeloEntrada / saída por milhão de tokens
opus15 / 75
sonnet (e fallback)3 / 15
haiku0.25 / 1.25

São constantes fixas em jsonl_watcher.rs, não preços ao vivo. A criação de cache é precificada a 1,25 vez a entrada e a leitura de cache a 0,1 vez.

Isolamento de configuração

fresh dirfresh diraccountCLAUDE_CONFIG_DIR per session
Cada sessão ganha seu próprio diretório de configuração; uma conta salva é compartilhada pelas suas sessões.

A precedência do diretório de configuração em create_isolated_session é: conta salva, depois diretório novo por sessão, depois login do host. Só o último deixa a variável de configuração sem definir.

CasoDiretório de configuração
Conta salva~/.hydra-ensemble/accounts/<provider>/<accountId>/, persistente e compartilhado pelas suas sessões
Configuração nova~/.hydra-ensemble/sessions/<id>/<provider>/, efêmero
NenhumDiretório do host como ~/.claude, ~/.codex, ~/.copilot, ~/.cursor, ~/.grok

Cada sessão também recebe HYDRA_ENSEMBLE_SESSION_ID no seu ambiente. A variável do provedor (CLAUDE_CONFIG_DIR para o Claude, CODEX_HOME para o Codex) é exportada na linha de lançamento. Para o Grok, o resolvedor prefere o diretório candidato que contém auth.json a um GROK_HOME herdado vazio.

O estado persistente vai para store.json: indentado com 2 espaços, escrito com debounce de 300 ms, descarregado no desligamento, com snapshots .bak.v{N} em migrações de schema e quarentena em caso de corrupção.

Worktrees e canvas

Um worktree é "gerenciado" quando seu realpath contém /.hydra-ensemble/worktrees/, normalizado para separadores do Windows e prefixos de caminho longo. A primeira entrada de git worktree list --porcelain é a principal.

A superfície canvas roda orquestração multiagente. Cada nó é um terminal de CLI ao vivo; os nós são ligados por setas e se coordenam por um barramento de arquivos em disco: BRIEFING.md, um inbox, sentinelas [HYDRA:*] e os helpers hydra-send e hydra-await, com encadeamento dos passos do workflow no servidor. Timers e limiares são constantes no topo de orchestration/bus.rs. Um orquestrador de equipes legado (orchestra/) ainda existe como overlay.

O inspetor de PR chama o gh a partir de forge/ e git/query.rs.

Decisões e limites

DecisãoEscolhidoRejeitadoPor quê
ShellTauri v2 com núcleo RustElectronO Electron não faz mais parte do projeto; binário nativo, sem runtime de Node
PTYportable-ptynode-ptyO mesmo crate que o WezTerm usa; roda no núcleo Rust
IPC da saídaMensagens Channel coalescidasUm evento por leituraA contagem de mensagens era o custo medido (spike F00.2)
Fonte de estadoAnalisador do PTY mais JSONL autoritativoSó o texto do PTYA correspondência de frases pode travar; as transcrições são a verdade
IsolamentoWorktree mais diretório de configuração por sessãoCheckout e login compartilhadosEvita colisões de arquivos, locks e históricos
CustoTarifas fixas por modeloNão declarado no repoAs tarifas vivem no código, então podem ficar desatualizadas
Acesso à forgeCLI ghNão declarado no repoReaproveita o login do gh que o usuário já tem

Limites conhecidos: o estado do PTY depende de frases do provedor, então uma mudança de texto numa CLI exige atualizar um marcador. Os GitHub Releases ainda não trazem assets de Linux para Arch. O harness e2e está bloqueado; a checagem de fumaça é o cenário MCP 09-canvas. O RFC da plataforma de plugins está marcado como pendente de revisão.

Arquivos