hydra-ensemble

Una app de escritorio multiplataforma que ejecuta sesiones de agentes de programación en paralelo, cada una con su propio PTY, git worktree y directorio de configuración.

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

Visión general

hydra ensemble es una terminal de escritorio para ejecutar varios agentes de programación lado a lado. Cada sesión es un PTY real que ejecuta la CLI de un proveedor (claude, codex, copilot, cursor, grok), normalmente dentro de su propio git worktree, con su propio directorio de configuración.

El problema que resuelve es la colisión. Dos agentes en un mismo checkout se pisan los archivos, y dos sesiones que comparten un directorio de configuración comparten logins, locks e historiales JSONL. Hydra da a cada sesión una rama y un directorio de configuración propios, de modo que el trabajo en paralelo sigue siendo separable.

Además, vigila cada sesión. Clasifica el stream del PTY en un estado en vivo, sigue la transcripción JSONL de la CLI para obtener tokens y costo, y muestra el resultado como una píldora de estado por sesión. También incluye un editor CodeMirror 6 con LSP, un conjunto de comandos de un clic, una terminal rápida flotante y un inspector de PR.

ÁreaQué hace
Terminalxterm.js con varias pestañas, ANSI, true color, ratón y redimensionado
AislamientoUn git worktree y un directorio de configuración de proveedor por sesión
Estadothinking, generating, idle, needs-attention a partir del stream del PTY
CostoDatos de tokens y costo leídos de la transcripción JSONL de la CLI
EditorCodeMirror 6 con diagnósticos LSP, hover, autocompletado y formateo
Inspector de PRLista y muestra el diff de los PR abiertos de GitHub mediante la CLI gh

Instalar y ejecutar

Los releases incluyen un .deb o AppImage en Linux, un .exe NSIS en Windows y un .dmg en macOS. Para compilar desde el código fuente necesitas un toolchain estable de Rust, Node 22 como herramienta de build del renderer, npm y git. Node no es una dependencia de runtime: la app distribuida es un binario nativo de Tauri.

Requisitos de build en Linux (Debian/Ubuntu)bash
sudo apt-get install libwebkit2gtk-4.1-dev libgtk-3-dev librsvg2-dev patchelf
Ejecutar desde el código fuentebash
git clone https://github.com/javabetatester/hydra-ensemble.git
cd hydra-ensemble
nvm use
npm install
npm run tauri:dev
Build de producción y el paquete de Archbash
npm run tauri:build
./scripts/install-arch.sh

Los instaladores quedan en src-tauri/target/release/bundle/. En Arch el script construye un .pkg.tar.zst nativo en dist/arch/ y lo instala, en todo el sistema con --system o en ~/.local sin sudo.

RequisitoNecesario para
Claude Code (u otra CLI de proveedor) en el PATHEjecutar sesiones
gh, instalado y autenticadoInspector de PR
typescript-language-server, gopls, pyright-langserver, rust-analyzerLSP del editor por lenguaje; resaltado simple en caso contrario
WebView2 RuntimeWindows; preinstalado en 11, incluido con el instalador en 10
AjusteEfecto
HYDRA_USER_DATAReemplaza el directorio de datos del usuario, incluido keybindings.json
~/.hydra-ensemble/keybindings.jsonAtajos del usuario; un comando que empieza con - elimina un atajo
centinela portable.txt o data/Redirige las raíces de sesiones y cuentas junto al binario
HYDRA_MCP=1Activa el plano de control MCP
Quality gatesbash
npm run typecheck
npm run lint
npm test
npm run build
cd src-tauri && cargo check

Arquitectura

ptybranch aptybranch bptybranch c
Cada sesión es una terminal conectada a su propio PTY y a su propia rama de worktree.

Un núcleo Rust es dueño de procesos, archivos y git. Un renderer React en el WebView de la plataforma es dueño de la UI. Se encuentran en un único módulo, src/renderer/tauri-api, el ú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 de Tauri vive en su módulo de dominio y debe registrarse en la lista generate_handler! de lib.rs.
  • Los streams calientes (datos del pty, mensajes LSP) usan un Channel por etiqueta de ventana; los demás eventos usan AppHandle::emit.
  • El estado de la sesión tiene dos fuentes: el analizador del PTY y el watcher de JSONL, que es el autoritativo.
  • Los contratos TypeScript compartidos viven en src/shared y se reflejan en structs serde camelCase en Rust.
  • Los secretos pasan por el llavero del SO (crate keyring) y nunca llegan al renderer.

Ciclo de vida de una sesión

  1. 1Worktreegit_create_worktree ejecuta git worktree add -b <name> bajo <repo>/.hydra-ensemble/worktrees/, a partir de la rama por defecto indicada o detectada. Si la rama existe, reintenta sin -b.
  2. 2Aislamiento de configuracióncreate_isolated_session escribe ~/.hydra-ensemble/sessions/<id>/meta.json y elige un directorio de configuración: primero una cuenta guardada, luego un directorio nuevo por sesión y, por último, el login del host.
  3. 3ArranquePtyManager::spawn inicia la CLI del proveedor en un par portable-pty con un entorno saneado y la variable del directorio de configuración exportada en la línea de lanzamiento.
  4. 4StreamLa salida del lector se decodifica, se coalesce y se envía a la ventana por un Channel; el mismo texto alimenta al analizador.
  5. 5SeguimientoEl analizador emite session:state; el watcher de JSONL resuelve la transcripción y emite el estado autoritativo, los tokens y el costo.
  6. 6CierreKill descarta el scrollback; destroy_isolated_session elimina el directorio de la sesión; git_remove_worktree ejecuta git worktree remove --force.

Detección de estado

ptyjsonlthinkinggeneratingidleattention
El analizador lee el texto del PTY y enciende una lámpara por sesión; el libro JSONL la anula.

PtyStreamAnalyzer lee la cola de la salida sin ANSI y compara la posición más reciente de cuatro familias de frases: working, thinking, idle y attention. Las familias son por proveedor (AnalyzerProfileId: Claude, Cursor, Grok, Generic). Para Claude, working es por ejemplo "esc to interrupt".

  • Los estados son SessionState: idle, thinking, generating, userInput, needsAttention.
  • El análisis se limita por frame a THROTTLE_MS = 80 y mira una ventana de texto reciente de 8000 caracteres.
  • Una marca de submit dura 8 s (SUBMIT_MARK_TTL_MS) y como máximo 45 s.
  • classify_pty_failure lee la misma cola para detectar fallos de rechazo, cuota y login.

La salida del analizador por sí sola puede fijar un estado erróneo, por eso el watcher de JSONL la anula. AnalyzerManager ejecuta un watchdog cada 2 s. Un estado autoritativo fijado con más de 8 s (AUTHORITATIVE_STALE_MS) junto con un estado working se reevalúa, lo que recupera las sesiones que dejaron de escribir.

Streaming del PTY

El coalescer existe por una medición registrada en el código (spike F00.2): el costo de tauri::ipc::Channel es la cantidad de mensajes, no los bytes. Fragmentos de 2 KB a alta tasa congelaron WebKitGTK a 0,4-0,7 FPS, mientras que el mismo volumen en mensajes de 32 KB corrió fluido a 165 MB/s.

ConstanteValorFunción
WINDOW12 msVacía incluso un buffer pequeño para que las pulsaciones sigan siendo interactivas
FLUSH_BYTES32 KBVaciado por tamaño; acota la memoria
CHANNEL_CAPACITY256Cola del lector al coalescer; cada elemento es como máximo un fragmento de 64 KiB
SCROLLBACK_CAP_BYTES4 MiBAnillo de reproducción por sesión

El backpressure es el canal acotado: cuando el consumidor se detiene, el lector se bloquea, el buffer del PTY en el kernel se llena y el proceso hijo se ralentiza. La ventana empieza en el primer byte y los fragmentos posteriores no la reinician, así que la latencia queda acotada por WINDOW.

PtyScrollback asigna un seq monótono a cada fragmento. Un snapshot lleva su seq y el renderer descarta los fragmentos en vivo con seq <= snapSeq, de modo que ningún byte de frontera se escribe dos veces: un byte duplicado dentro de una secuencia de escape ANSI corrompe el frame. Un respawn reinicia el anillo y seq vuelve a 0.

pty/env.rs elimina LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, las variables de inyección DYLD_* y NODE_OPTIONS de cada entorno que se lanza.

JSONL y costo

opussonnethaikujsonlcost
El watcher sigue el libro JSONL y valora los tokens por la tarifa del modelo en el medidor de costo.

JsonlWatcher sigue el <uuid>.jsonl de Claude, acumulando tokens, costo y contexto, y deriva el estado del turno, el nombre de sesión de la CLI y el id de reanudación. Un lanzamiento pasa --session-id <uuid>, así que resolver el archivo es una búsqueda directa; un escaneo por recencia es el respaldo tras una ventana.

  • Cadencias: RESOLVE_POLL 3000 ms, TAIL_POLL 5000 ms, con notify como señal principal.
  • Re-pin: /clear y --fork-session crean un nuevo jsonl en el mismo directorio de proyecto. Re-pin requiere evidencia de session::binding::arbitrate (linaje de fork o un /clear tecleado en 30 s); nunca se adopta una sesión externa más nueva.
  • Claims: un mapa compartido de uuid a sesión evita que dos sesiones en el mismo cwd adopten el mismo archivo.
  • Catch-up seguro: al adjuntar o hacer re-pin, los estados working derivados de líneas antiguas no se emiten, de modo que un archivo que terminó en un tool_use no puede fijar Generating en una sesión detenida.
ModeloEntrada / salida por millón de tokens
opus15 / 75
sonnet (y fallback)3 / 15
haiku0.25 / 1.25

Son constantes fijas en jsonl_watcher.rs, no precios en vivo. La creación de caché se valora a 1,25 veces la entrada y la lectura de caché a 0,1 veces.

Aislamiento de configuración

fresh dirfresh diraccountCLAUDE_CONFIG_DIR per session
Cada sesión recibe su propio directorio de configuración; una cuenta guardada la comparten sus sesiones.

La precedencia del directorio de configuración en create_isolated_session es: cuenta guardada, luego directorio nuevo por sesión, luego login del host. Solo el último deja sin definir la variable de configuración.

CasoDirectorio de configuración
Cuenta guardada~/.hydra-ensemble/accounts/<provider>/<accountId>/, persistente y compartido por sus sesiones
Configuración nueva~/.hydra-ensemble/sessions/<id>/<provider>/, efímero
NingunoDirectorio del host como ~/.claude, ~/.codex, ~/.copilot, ~/.cursor, ~/.grok

Cada sesión también recibe HYDRA_ENSEMBLE_SESSION_ID en su entorno. La variable del proveedor (CLAUDE_CONFIG_DIR para Claude, CODEX_HOME para Codex) se exporta en la línea de lanzamiento. Para Grok, el resolvedor prefiere el directorio candidato que contiene auth.json sobre un GROK_HOME heredado vacío.

El estado persistente va a store.json: indentado con 2 espacios, escrito con un debounce de 300 ms, vaciado al apagar, con snapshots .bak.v{N} en migraciones de esquema y cuarentena por corrupción.

Worktrees y canvas

Un worktree es "gestionado" cuando su realpath contiene /.hydra-ensemble/worktrees/, normalizado para separadores de Windows y prefijos de ruta larga. La primera entrada de git worktree list --porcelain es la principal.

La superficie canvas ejecuta orquestación multiagente. Cada nodo es una terminal de CLI en vivo; los nodos se conectan con flechas y se coordinan mediante un bus de archivos en disco: BRIEFING.md, un inbox, centinelas [HYDRA:*] y los helpers hydra-send y hydra-await, con encadenamiento de pasos del workflow en el servidor. Los timers y umbrales son constantes al inicio de orchestration/bus.rs. Un orquestador de equipos heredado (orchestra/) sigue existiendo como overlay.

El inspector de PR invoca gh desde forge/ y git/query.rs.

Decisiones y límites

DecisiónElegidoDescartadoPor qué
ShellTauri v2 con núcleo RustElectronElectron ya no forma parte del proyecto; binario nativo, sin runtime de Node
PTYportable-ptynode-ptyEl mismo crate que usa WezTerm; corre en el núcleo Rust
IPC para la salidaMensajes Channel coalescidosUn evento por lecturaLa cantidad de mensajes era el costo medido (spike F00.2)
Fuente de estadoAnalizador del PTY más JSONL autoritativoSolo el texto del PTYLa coincidencia de frases puede fijarse; las transcripciones son la verdad
AislamientoWorktree más directorio de configuración por sesiónCheckout y login compartidosEvita colisiones de archivos, locks e historiales
CostoTarifas fijas por modeloNo indicado en el repoLas tarifas viven en el código, así que pueden quedar obsoletas
Acceso a la forgeCLI ghNo indicado en el repoReutiliza el login de gh que el usuario ya tiene

Límites conocidos: el estado del PTY depende de frases del proveedor, así que un cambio de redacción en una CLI requiere actualizar un marcador. Los GitHub Releases todavía no incluyen assets de Linux para Arch. El harness e2e está bloqueado; la comprobación de humo es el escenario MCP 09-canvas. El RFC de la plataforma de plugins está marcado como pendiente de revisión.

Archivos