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.
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.
| Área | O que faz |
|---|---|
| Terminal | xterm.js com várias abas, ANSI, true color, mouse e redimensionamento |
| Isolamento | Um git worktree e um diretório de configuração de provedor por sessão |
| Status | thinking, generating, idle, needs-attention a partir do stream do PTY |
| Custo | Dados de tokens e custo lidos da transcrição JSONL da CLI |
| Editor | CodeMirror 6 com diagnósticos LSP, hover, autocomplete e formatação |
| Inspetor de PR | Lista 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.
sudo apt-get install libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev patchelfgit clone https://github.com/javabetatester/hydra-ensemble.git
cd hydra-ensemble
nvm use
npm install
npm run tauri:devnpm run tauri:build
./scripts/install-arch.shOs 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.
| Requisito | Necessário para |
|---|---|
| Claude Code (ou outra CLI de provedor) no PATH | Rodar sessões |
| gh, instalado e autenticado | Inspetor de PR |
| typescript-language-server, gopls, pyright-langserver, rust-analyzer | LSP do editor por linguagem; realce simples caso contrário |
| WebView2 Runtime | Windows; já vem no 11, incluído no instalador no 10 |
| Configuração | Efeito |
|---|---|
| HYDRA_USER_DATA | Substitui o diretório de dados do usuário, incluindo keybindings.json |
| ~/.hydra-ensemble/keybindings.json | Atalhos 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=1 | Ativa o plano de controle MCP |
npm run typecheck
npm run lint
npm test
npm run build
cd src-tauri && cargo checkArquitetura
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/*.
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
- 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.
- 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.
- 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.
- 4StreamA saída do leitor é decodificada, coalescida e enviada à janela por um Channel; o mesmo texto alimenta o analisador.
- 5AcompanhamentoO analisador emite session:state; o watcher de JSONL resolve a transcrição e emite o estado autoritativo, os tokens e o custo.
- 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
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.
| Constante | Valor | Papel |
|---|---|---|
| WINDOW | 12 ms | Descarrega até um buffer pequeno para as teclas continuarem interativas |
| FLUSH_BYTES | 32 KB | Descarga por tamanho; limita a memória |
| CHANNEL_CAPACITY | 256 | Fila do leitor para o coalescer; cada item é no máximo um pedaço de 64 KiB |
| SCROLLBACK_CAP_BYTES | 4 MiB | Anel 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
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.
| Modelo | Entrada / saída por milhão de tokens |
|---|---|
| opus | 15 / 75 |
| sonnet (e fallback) | 3 / 15 |
| haiku | 0.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
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.
| Caso | Diretó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 |
| Nenhum | Diretó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ão | Escolhido | Rejeitado | Por quê |
|---|---|---|---|
| Shell | Tauri v2 com núcleo Rust | Electron | O Electron não faz mais parte do projeto; binário nativo, sem runtime de Node |
| PTY | portable-pty | node-pty | O mesmo crate que o WezTerm usa; roda no núcleo Rust |
| IPC da saída | Mensagens Channel coalescidas | Um evento por leitura | A contagem de mensagens era o custo medido (spike F00.2) |
| Fonte de estado | Analisador do PTY mais JSONL autoritativo | Só o texto do PTY | A correspondência de frases pode travar; as transcrições são a verdade |
| Isolamento | Worktree mais diretório de configuração por sessão | Checkout e login compartilhados | Evita colisões de arquivos, locks e históricos |
| Custo | Tarifas fixas por modelo | Não declarado no repo | As tarifas vivem no código, então podem ficar desatualizadas |
| Acesso à forge | CLI gh | Não declarado no repo | Reaproveita 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
- docs/MAPA.mdMapa canônico de onde cada domínio vive
- docs/ARCHITECTURE.mdArquitetura normativa e os dois subsistemas de orquestração
- src-tauri/src/lib.rsComposição e registro de generate_handler!
- src-tauri/src/pty/manager.rsPtyManager, PtyScrollback, spawn e write
- src-tauri/src/pty/coalesce.rsCoalescer de 12 ms / 32 KB com os números do spike
- src-tauri/src/pty/env.rsLista negra de ambiente e resolução do shell
- src-tauri/src/analyzer/stream.rsMáquina de estados do PtyStreamAnalyzer
- src-tauri/src/analyzer/manager.rsAnalisadores por sessão e o watchdog
- src-tauri/src/analyzer/profiles.rsTabelas de marcadores por provedor
- src-tauri/src/claude/jsonl_watcher.rsAcompanhamento da transcrição, acúmulo de custo, re-pin
- src-tauri/src/session/config_isolation.rsDiretórios de configuração de sessão e conta
- src-tauri/src/git/worktree.rsCriar, listar e remover worktrees
- src-tauri/src/store/mod.rsstore.json com debounce e recuperação
- src/renderer/tauri-apiO único módulo que importa @tauri-apps/*
- src/renderer/state/keybinds.tsAtalhos padrão