Herdr: un tmux para agentes

Cuando tienes cinco agentes y ninguna terminal donde caben

Hace poco conté aquí cómo construí parallel-work, un plugin de orquestación multi-agente que reparte una funcionalidad en carriles paralelos: un coordinador reparte el trabajo, varios builders construyen cada uno en su propio worktree, un revisor verifica cada PR, y QA y arquitecto cierran cada ola. Sobre el papel es harness engineering de manual. En la práctica, en cuanto lo pones a correr de verdad, te topas con una pregunta que el diseño no responde: ¿dónde vive toda esa manada de agentes mientras trabaja?

Porque eso es exactamente lo que tienes cuando pasas de "un agente en una pestaña" a cinco corriendo en paralelo sobre distintos worktrees: dejas de tener una conversación y empiezas a tener una manada. Uno está compilando, otro está bloqueado esperando tu aprobación, otro terminó hace diez minutos y no te has enterado, y un cuarto lleva un rato haciendo algo que no querías. Los gestores de agentes de escritorio resuelven parte de esto con una GUI bonita, pero atan la manada a la máquina donde está el GUI. Y tmux, que sí te da sesiones persistentes en cualquier caja por ssh, no tiene ni idea de qué es un agente: para él todo son procesos y bytes.

Herdr se planta justo en ese hueco — de ahí el nombre: herdr, de herder, pastor; alguien tiene que pastorear la manada — y por eso me interesó tanto: es la capa de runtime que le encaja a mi flujo de orquestación. Su propia definición lo dice sin rodeos: es a los agentes de código lo que tmux es a las terminales, un multiplexor de agentes. Un coordinador que reparte carriles necesita precisamente lo que Herdr da de serie —panes persistentes que sobreviven al portátil, attach remoto, y estado semántico de cada agente a la vista— para que la manada escale sin que se te escape ninguno.

Qué es Herdr

Herdr es un único binario de Rust —sin Electron, sin cuenta, sin telemetría— que corre donde corren tus agentes: un servidor, un Mac Mini, una VM sandbox, cualquier cosa a la que puedas hacer ssh. Es open source con licencia dual: AGPL-3.0 para todo el mundo, y licencia comercial para organizaciones que no puedan cumplir el AGPL. Tú te reenganchas desde cualquier terminal, incluido el móvil. Esa es la primera diferencia real frente a un gestor de escritorio: el trabajo vive en la máquina donde tiene sentido que viva, y el cliente es desechable. Cierras el portátil y nada muere: te vas a por un café, te reenganchas desde otra máquina, y la manada sigue exactamente donde la dejaste.

Sobre esa base persistente, Herdr añade lo que ni tmux ni Zellij te dan: conciencia de agentes. Cada agente corre en su propio PTY real —no es una vista de chat reconstruida, es el proceso de verdad— y Herdr te muestra su estado semántico de un vistazo: working, blocked, done, idle. Ese estado no depende de que el agente lo reporte: Herdr usa hooks de integración cuando el agente los trae (Claude Code, Codex y una lista larga) y, si no, lo deduce leyendo la propia pantalla del pane — con una detección de blocked deliberadamente estricta para no dar falsas alarmas. Eso es exactamente lo que te falta cuando tienes cinco corriendo: saber, sin ir pestaña por pestaña, cuál necesita algo de ti ahora mismo.

Así se ve la manada pastando: tres agentes en panes contiguos —cada uno con un modelo distinto—, las tabs del workspace arriba, y en la barra lateral los workspaces y la lista de agentes agrupados con su estado de un vistazo.

Los diferenciales que a mí me hicieron quedarme:

• Corre dentro de tu terminal. No es un emulador que sustituye a Ghostty/Kitty/iTerm ni un dashboard en el navegador. Es una capa por debajo, como tmux.
• Attach remoto nativo. herdr --remote workbox busca Herdr en el host y, si no lo encuentra, se ofrece a instalarlo en ~/.local/bin — cero aprovisionamiento manual, al estilo del server de VS Code. Además hace de puente con tu portapapeles local (incluido pegar imágenes) y usa tus keybindings locales en la sesión remota.
• Los agentes pueden orquestarlo a él. Hay una CLI y una API por socket JSON, así que un agente puede crear panes, lanzar comandos y esperar a que otro termine. Esto es lo que lo convierte en pieza de orquestación y no solo en un visor.

El modelo técnico: paneles reales y una superficie de control

El modelo mental viene de tmux y se hereda tal cual: prefijo ctrl+b, panes persistentes, detach/reattach como esperas. La diferencia de trato es que Herdr es mouse-first: puedes clicar panes, arrastrar bordes y usar menús contextuales sin aprenderte un solo atajo. Los atajos son una capa opcional encima, no un peaje de entrada.

Lo que de verdad abre la puerta a construir cosas encima es la superficie de control: además de la interacción manual, todo lo que ves se puede pilotar desde la CLI o el socket. Un ejemplo sacado de su documentación:

# crear la estructura de un workspace
herdr workspace create --cwd ~/project --label api
herdr tab create --label logs

# dividir un pane y lanzar trabajo
herdr pane split 1-1 --direction right
herdr pane run 1-2 "just test"

# esperar, inspeccionar y continuar
herdr wait agent-status 1-1 --status done
herdr pane read 1-2 --source recent-unwrapped

Ese herdr wait agent-status ... --status done es la primitiva interesante: convierte "estar pendiente de una pestaña" en algo que un script —o un orquestador— puede esperar de forma programática.

El ecosistema de plugins

Aquí es donde Herdr se vuelve extensible sin dejar de ser lean. Un plugin no es una integración vía SDK: es un directorio con un manifiesto herdr-plugin.toml y unos comandos que Herdr puede lanzar. Puede estar escrito en lo que sea que tu máquina sepa ejecutar —Bash, JavaScript, Lua, un binario de Rust— porque Herdr se queda con la parte de "host" (instalación, validación del manifiesto, keybindings, panes, eventos, contexto de invocación, acceso al socket) y el plugin se queda con su implementación.

La frase que mejor lo resume, de sus docs: no hay un SDK aparte, toda la CLI es la API del plugin. Lo que tú puedes hacer con herdr ..., un plugin puede hacerlo también, normalmente a través de HERDR_BIN_PATH.

El manifiesto declara actions, event hooks (por ejemplo worktree.created), panes gestionados y manejadores de enlaces. Para que se vea lo poco que hace falta, este es (recortado) el manifiesto real de mi propio plugin, del que hablaré en el siguiente post:

id = "tds.keymap"
name = "Keymap Palette"
description = "List herdr keybindings in an overlay and run the ones with a CLI equivalent"

[[panes]]
id = "palette"
placement = "overlay"
command = ["node", "src/keymap.ts"]  # Node ≥ 24 ejecuta .ts nativo

[[actions]]
id = "open_palette"
title = "Open keybindings palette"
command = ["bash", "open_palette.sh"]

Y la distribución es deliberadamente sin fricción: el marketplace se autoindexa desde el topic de GitHub herdr-plugin. No hay cola de revisión ni formulario: añades el topic a un repo público con su manifiesto y en el siguiente refresco aparece. Hoy hay más de un centenar de plugins de la comunidad descubiertos así.

(Que no haya revisión también significa que instalas bajo tu propia responsabilidad: un plugin es código que corre en tu máquina. Merece la pena decirlo.)

Dónde encaja esto

Herdr me interesa por lo que representa más que por lo que hace hoy: mueve la orquestación de agentes de "una app que mira una máquina" a "una primitiva de terminal, persistente, remota y pilotable por API". Ese último punto —que un agente pueda conducir el multiplexor donde viven los demás agentes— es justo la clase de superficie sobre la que se pueden montar coordinadores de verdad.

Nota de interés: el propio Claude Code acaba de sacar algo en esta dirección, el Agent view (claude agents, en research preview), y como parallel-work es un plugin de Claude Code, era obligado probarlo. Está bien resuelto para lo que es —agrupa las sesiones por estado, deja hacer peek sin abrir la sesión entera, y mueve las ediciones a worktrees automáticamente—, pero es un visor local muy cómodo, no una pieza de orquestación: solo local (las sesiones mueren al apagar la máquina, sin attach remoto), sin filas propias para los subagentes que lanza una sesión, y sobre todo sin CLI ni socket que un coordinador pueda pilotar. Herdr es una primitiva de orquestación precisamente porque expone esa API. Dicho esto, salió hace nada: habrá que ver cómo evoluciona.

Y aquí se cierra el círculo con parallel-work. Cuando Herdr está presente, el coordinador aloja cada carril —su worktree, su sesión, su rama— en un tab propio, y escalar de dos agentes a cinco deja de ser «¿dónde meto todo esto?» para ser un tab más. Pero el coordinador no delega el juicio en la infraestructura: sondea la ola entera por cambio de estado y confirma contra los artefactos durables —el PR, el HANDOFF.md, el STATE.md—, nunca contra el texto de una pestaña. Mi plugin impone la disciplina (Design Lock, olas, puertas de verificación); Herdr aporta el sustrato donde esa manada se lanza y se deja observar. La persistencia vive en los artefactos, no en los panes.

De hecho, usarlo a diario me llevó a escribir mi propio plugin para él: herdr-keymap, una paleta de atajos que además los ejecuta. Pero esa historia —por qué existe, cómo está hecho y la decisión de diseño de la que más orgulloso estoy— la contaré en otro post.

¿Lo estás usando ya para orquestar tus agentes? Me interesa saber cómo montas la manada.