Automatización con agentes

Usa Herdr como capa de automatización para agentes de programación. Un script puede controlarlos, o un agente puede crear trabajo para otros agentes, inspeccionar su estado y recoger sus resultados. Elige la primitiva que encaje con la tarea.

Tres primitivas

Primitiva	Responsabilidad
Disposición (workspace, tab y topología de paneles)	Crear y organizar ubicaciones de terminal.
Panel	Controlar una terminal en bruto: ejecutar comandos, enviar entrada, leer la salida y esperar una salida.
Agente	Controlar un agente de programación reconocido por nombre o por panel, y su estado de ciclo de vida.

Un panel existe contenga o no un agente. Un agente es el proceso reconocido que corre ahora dentro de un panel. Por eso agent start requiere un panel de shell existente y nunca crea, divide ni mueve la disposición.

Crear un espacio de trabajo crea también su primera pestaña y su panel raíz; crear una pestaña crea su panel raíz. Usa el ID de panel devuelto para el primer proceso, y divide solo cuando esa disposición necesite otra terminal.

Los comandos de creación imprimen JSON. Toma los IDs de la respuesta en vez de predecirlos:

created=$(herdr workspace create --cwd ~/proyecto --label api --no-focus)
pane_id=$(printf '%s\n' "$created" | jq -r '.result.root_pane.pane_id')

split=$(herdr pane split "$pane_id" --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')

workspace create devuelve .result.workspace, .result.tab y .result.root_pane. tab create devuelve .result.tab y .result.root_pane. pane split devuelve el panel nuevo como .result.pane.

Mover un panel a otro espacio de trabajo cambia su ID de panel cualificado por espacio de trabajo. Después de cualquier pane move, continúa con .result.move_result.pane.pane_id; la respuesta conserva el valor antiguo en .result.move_result.previous_pane_id. Un proceso en marcha conserva el entorno de Herdr que tenía al lanzarse, pero el HERDR_PANE_ID antiguo sigue siendo un alias de esa terminal, así que --current sigue siendo seguro. Los comandos nuevos siguen resolviendo el agente por nombre después del movimiento, pero una espera ya en curso termina con agent_not_running.

Usa los comandos de panel para shells, pruebas, servidores, vigilantes de CI y demás procesos de terminal corrientes. Usa los comandos de agente cuando Herdr necesite saber qué agente está corriendo o si está working, blocked, done, idle o unknown.

Identidad y lanzamiento de agentes

Un ID de panel como w1:p2 identifica la ubicación de la terminal. Un nombre de agente como reviewer es un alias cómodo para el agente actual de ese panel. Los nombres deben cumplir [a-z][a-z0-9_-]{0,31} y ser únicos entre los agentes vivos. El alias se borra cuando ese agente sale, se libera o se sustituye; no renombra el panel de forma permanente.

Los comandos de agente aceptan un nombre único de agente vivo o el ID del panel que lo aloja en ese momento.

Un panel de shell disponible es el que está en el prompt de su shell interactivo: el propio shell tiene el primer plano, sin ningún comando, editor ni agente en marcha. Devuelve el panel a su prompt antes de llamar a agent start.

--kind selecciona un agente compatible y su ejecutable canónico. Los tipos admitidos son pi, claude, codex, gemini, cursor, devin, agy, cline, omp, mastracode, opencode, copilot, kimi, kiro, droid, amp, grok, hermes, kilo, qodercli, qwen, letta, maki y muse. Los argumentos tras -- se pasan sin cambios a ese ejecutable.

Un agent start correcto devuelve solo cuando Herdr detecta el agente esperado en esa misma terminal y lo marca como listo para entrada interactiva. Si la detección informa de blocked durante el arranque, el comando devuelve agent_not_ready de inmediato. El nombre sigue disponible para agent read y agent send-keys, y queda listo para prompts cuando la detección informe de idle. El arranque espera 30 segundos por defecto; --timeout debe ser mayor que 3000 y no superar 300000 milisegundos.

herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4

Los agentes lanzados a mano se detectan automáticamente y se pueden referenciar por ID de panel. Dale un nombre a uno cuando te venga bien un destino estable y legible:

herdr agent get w1:p2
herdr agent rename w1:p2 reviewer

Elige la superficie de control

Objetivo	Comando
Ejecutar un comando de shell y enviarlo	pane run
Enviar texto literal sin Intro	pane send-text
Enviar teclas de terminal o combinaciones con modificadores	pane send-keys
Esperar un texto o una expresión regular	pane wait-output
Arrancar un agente compatible en un panel existente	agent start
Enviar un prompt, esperando o no	agent prompt
Enviar teclas a la interfaz interactiva de un agente	agent send-keys
Esperar un estado de ciclo de vida del agente	agent wait

agent prompt envía el texto más un Intro codificado y respeta el modo de pegado entre corchetes activo de la terminal. Puede enviar un prompt a un agente que ya está trabajando. Si el agente ya está blocked, devuelve agent_blocked sin enviar entrada; inspecciona el diálogo y usa agent send-keys para responder a propósito. Usa agent send-keys para interacciones como esc, up, enter o ctrl+c; escape se acepta como alias de esc. Usa los comandos de entrada de panel cuando quieras control de terminal en bruto de forma deliberada.

La entrada de panel se dirige a la terminal, sea quien sea su ocupante actual. La entrada de agente resuelve el agente vivo y rechaza la operación si ese agente ya no controla el panel.

agent prompt --wait rechaza con agent_blocked a un agente ya bloqueado, sin enviar entrada ni arrancar la espera. En caso contrario, escribe el prompt y un Intro retardado como un único envío ordenado antes de esperar. En Windows, Codex recibe un límite de pegado antes del Intro para que el envío no dependa del tamaño del prompt. El tiempo límite de quien llama incluye el tiempo de envío. Si el prompt partía de otro estado que no fuera trabajando, Herdr espera hasta cinco segundos tras el envío para observar working o blocked. Si no, devuelve agent_prompt_stalled; si el tiempo límite de quien llama expira antes, devuelve el error timeout normal. Así se evita que cambios de idle, done o de sesión no relacionados completen la espera. Una vez observada actividad, Herdr espera al estado estable pedido. No sigue turnos individuales. Si el agente ya estaba trabajando, la finalización de ese turno puede satisfacer la espera. Un agent wait suelto observa el agente actual y devuelve de inmediato si su estado ya coincide. Ambos comandos usan por defecto idle, done o blocked. Repite --until para aceptar varios estados exactos, por ejemplo --until idle --until done; usa --until unknown de forma explícita cuando lo necesites. En agent prompt, --until requiere --wait.

idle y done significan los dos que el agente está listo para recibir entrada. La CLI y la API usan el estado de visto del servidor: done es en espera pero aún no marcado como visto, los comandos explícitos pane focus y agent focus marcan el destino como visto, y las lecturas no. Cada cliente de la interfaz lleva la cuenta de las finalizaciones vistas por separado, así que su marca Done puede diferir de la CLI o de otro cliente. blocked significa que Herdr ha reconocido una interfaz de aprobación o pregunta. unknown significa que hay un agente pero Herdr no puede clasificar su ciclo de vida con seguridad; no demuestra que haya terminado bien. Usa estados --until exactos cuando esa distinción importe.

La preparación al arrancar, restaurar una conversación en espera y cambiar de conversación no cuentan como trabajo completado. Un agente que empieza a trabajar de inmediato puede terminar su primera tarea sin que Herdr haya visto antes un prompt en espera. Las respuestas de agente pueden incluir completion_seq, que identifica la transición a idle actual como trabajo completado con independencia de quién lo haya visto. Coincide con el state_change_seq de esa transición; el arranque y los cambios de sesión no lo fijan. Los servidores antiguos pueden omitir este campo. Los clientes conectados a servidores antiguos usan los estados de trabajo observados para proteger las marcas Done, así que pueden perderse un turno que empieza y termina entre dos actualizaciones.

Un tiempo límite o un agent_prompt_stalled no demuestran que no se enviara entrada. Lee el agente antes de reintentar para no enviar el mismo prompt dos veces. Los IDs y los nombres de agente pertenecen a un solo servidor; seleccionar otra máquina en la interfaz no cambia el destino de los comandos de la CLI que corren en un panel existente.

pane wait-output no interpreta el ciclo de vida de los agentes. Sondea la instantánea de terminal seleccionada y la busca de inmediato, así que el texto que ya estaba puede coincidir. La fuente por defecto se llama recent; la comparación la trata como salida reciente desenvuelta de las últimas 80 filas de terminal pintadas. --lines cambia ese límite, y --regex usa la sintaxis de expresiones regulares de Rust y compara línea a línea.

En la CLI, tanto pane read como agent read imprimen directamente el texto de la terminal. Por defecto es texto UTF-8 sin secuencias ANSI; usa --format ansi o --ansi para conservarlas cuando la fuente las expone. La fuente detection es siempre texto plano. En las fuentes recientes, --lines N selecciona las últimas N filas de terminal pintadas antes del desenvuelto opcional; sin él, las lecturas toman 80 filas por defecto. En visible y detection, omitir --lines devuelve la instantánea completa, e indicarlo conserva las últimas N líneas delimitadas por salto de línea. La API de socket devuelve el texto en .result.read.text.

Lecturas del historial en la pantalla alternativa

Los agentes a pantalla completa, como Claude Code y OpenCode, pintan el historial de la conversación en la pantalla alternativa de la terminal, no en el historial de Herdr. En un agente reconocido, en espera y al final de su transcripción, las lecturas de texto desde recent o recent-unwrapped usan automáticamente la interfaz de desplazamiento con ratón del agente cuando --lines pide más que la pantalla visible. Herdr recoge páginas solapadas y devuelve la vista al final antes de completar la lectura. Lo mismo se aplica a pane read cuando el panel contiene ese agente; no requiere ninguna opción adicional.

Las demás lecturas son pasivas. Herdr no mueve la vista de la aplicación en las lecturas visible, detection o ANSI, en las esperas de salida y suscripciones, en un agente desplazado a mano, en una conexión directa ni en una aplicación que no informe de la rueda del ratón. Un agent read --lines N explícito que necesite historial de la pantalla alternativa devuelve agent_not_idle mientras el agente está trabajando, bloqueado o desconocido; espera a que quede en espera y reintenta, o usa --source visible. Las demás lecturas recientes devuelven la pantalla disponible y el historial de Herdr, como siempre.

Si sigue sin haber una respuesta completa disponible, pide al agente que la escriba en Markdown en un directorio temporal y responda solo con la ruta del fichero, y léelo directamente.

Los comandos agent start, agent prompt y agent wait correctos devuelven el agente actual en .result.agent. pane wait-output devuelve .result.pane_id, .result.matched_line y la instantánea que ha coincidido en .result.read.

Los comandos de espera no tienen tiempo límite por defecto y pueden esperar indefinidamente. Ante un tiempo límite u otro error del servidor, los comandos de la CLI imprimen un error JSON por la salida de error y salen con código 1; una sintaxis de CLI no válida sale con código 2.

Recetas

Arrancar un ayudante, darle trabajo y esperar a que ese trabajo se asiente:

split=$(herdr pane split --current --direction right --no-focus)
review_pane=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')
herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4
herdr agent prompt reviewer "Revisa el diff actual" --wait --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 120

Esperar a que un agente pida entrada, inspeccionarlo e interactuar con su interfaz:

herdr agent wait reviewer --until blocked --timeout 120000
herdr agent read reviewer --source recent-unwrapped --lines 80
herdr agent send-keys reviewer esc

Ejecutar un proceso corriente y esperar su salida sin tratarlo como agente:

herdr pane run w1:p3 "just test --watch"
herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000

Mira la referencia de la CLI para la lista completa de comandos y opciones. El autocompletado del shell expone el mismo árbol de comandos de forma interactiva.