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.
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.
| Área | Qué hace |
|---|---|
| Terminal | xterm.js con varias pestañas, ANSI, true color, ratón y redimensionado |
| Aislamiento | Un git worktree y un directorio de configuración de proveedor por sesión |
| Estado | thinking, generating, idle, needs-attention a partir del stream del PTY |
| Costo | Datos de tokens y costo leídos de la transcripción JSONL de la CLI |
| Editor | CodeMirror 6 con diagnósticos LSP, hover, autocompletado y formateo |
| Inspector de PR | Lista 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.
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.shLos 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.
| Requisito | Necesario para |
|---|---|
| Claude Code (u otra CLI de proveedor) en el PATH | Ejecutar sesiones |
| gh, instalado y autenticado | Inspector de PR |
| typescript-language-server, gopls, pyright-langserver, rust-analyzer | LSP del editor por lenguaje; resaltado simple en caso contrario |
| WebView2 Runtime | Windows; preinstalado en 11, incluido con el instalador en 10 |
| Ajuste | Efecto |
|---|---|
| HYDRA_USER_DATA | Reemplaza el directorio de datos del usuario, incluido keybindings.json |
| ~/.hydra-ensemble/keybindings.json | Atajos 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=1 | Activa el plano de control MCP |
npm run typecheck
npm run lint
npm test
npm run build
cd src-tauri && cargo checkArquitectura
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/*.
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
- 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.
- 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.
- 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.
- 4StreamLa salida del lector se decodifica, se coalesce y se envía a la ventana por un Channel; el mismo texto alimenta al analizador.
- 5SeguimientoEl analizador emite session:state; el watcher de JSONL resuelve la transcripción y emite el estado autoritativo, los tokens y el costo.
- 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
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.
| Constante | Valor | Función |
|---|---|---|
| WINDOW | 12 ms | Vacía incluso un buffer pequeño para que las pulsaciones sigan siendo interactivas |
| FLUSH_BYTES | 32 KB | Vaciado por tamaño; acota la memoria |
| CHANNEL_CAPACITY | 256 | Cola del lector al coalescer; cada elemento es como máximo un fragmento de 64 KiB |
| SCROLLBACK_CAP_BYTES | 4 MiB | Anillo 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
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.
| Modelo | Entrada / salida por millón de tokens |
|---|---|
| opus | 15 / 75 |
| sonnet (y fallback) | 3 / 15 |
| haiku | 0.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
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.
| Caso | Directorio 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 |
| Ninguno | Directorio 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ón | Elegido | Descartado | Por qué |
|---|---|---|---|
| Shell | Tauri v2 con núcleo Rust | Electron | Electron ya no forma parte del proyecto; binario nativo, sin runtime de Node |
| PTY | portable-pty | node-pty | El mismo crate que usa WezTerm; corre en el núcleo Rust |
| IPC para la salida | Mensajes Channel coalescidos | Un evento por lectura | La cantidad de mensajes era el costo medido (spike F00.2) |
| Fuente de estado | Analizador del PTY más JSONL autoritativo | Solo el texto del PTY | La coincidencia de frases puede fijarse; las transcripciones son la verdad |
| Aislamiento | Worktree más directorio de configuración por sesión | Checkout y login compartidos | Evita colisiones de archivos, locks e historiales |
| Costo | Tarifas fijas por modelo | No indicado en el repo | Las tarifas viven en el código, así que pueden quedar obsoletas |
| Acceso a la forge | CLI gh | No indicado en el repo | Reutiliza 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
- docs/MAPA.mdMapa canónico de dónde vive cada dominio
- docs/ARCHITECTURE.mdArquitectura normativa y los dos subsistemas de orquestación
- src-tauri/src/lib.rsComposición y registro de generate_handler!
- src-tauri/src/pty/manager.rsPtyManager, PtyScrollback, spawn y write
- src-tauri/src/pty/coalesce.rsCoalescer de 12 ms / 32 KB con los números del spike
- src-tauri/src/pty/env.rsLista negra de entorno y resolución del shell
- src-tauri/src/analyzer/stream.rsMáquina de estados de PtyStreamAnalyzer
- src-tauri/src/analyzer/manager.rsAnalizadores por sesión y el watchdog
- src-tauri/src/analyzer/profiles.rsTablas de marcadores por proveedor
- src-tauri/src/claude/jsonl_watcher.rsSeguimiento de la transcripción, acumulación de costo, re-pin
- src-tauri/src/session/config_isolation.rsDirectorios de configuración de sesión y cuenta
- src-tauri/src/git/worktree.rsCrear, listar y eliminar worktrees
- src-tauri/src/store/mod.rsstore.json con debounce y recuperación
- src/renderer/tauri-apiEl único módulo que importa @tauri-apps/*
- src/renderer/state/keybinds.tsAtajos por defecto