Herdr — Gestión de espacios de trabajo en terminal

Herdr

Herdr organiza las terminales en espacios de trabajo, pestañas y paneles, reconoce los agentes de codificación que se ejecutan dentro de los paneles y expone la sesión actual a través de la CLI herdr.

Antes de emitir cualquier comando de control, verifica que este agente se esté ejecutando dentro de un panel administrado por Herdr:

test "${HERDR_ENV:-}" = 1

Si la verificación falla, indica que no estás ejecutándote dentro de Herdr y detente. No inspecciones ni controles la sesión enfocada de Herdr desde fuera de Herdr.

Cuando la verificación sea exitosa, el binario herdr en PATH se comunica con la sesión actual. Úsalo para inspeccionar trabajo vecino, crear diseños de terminal, iniciar agentes y comandos, leer la salida y esperar cambios de estado.

Aprende la CLI actual

El binario instalado es la autoridad en cuanto a la sintaxis de comandos. Comienza con:

herdr --help

Luego imprime el grupo de comandos relevante ejecutando el grupo sin un subcomando:

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session

No ejecutes herdr solo para descubrir; eso inicia o adjunta la TUI. No pruebes un comando anidado mutante omitiendo argumentos. Comandos como herdr workspace create son válidos con valores predeterminados y se ejecutarán.

La mayoría de los comandos de control devuelven JSON. Lee los identificadores y el estado de esas respuestas en lugar de predecirlos.

Comprende el diseño, los paneles y los agentes

Elige la primitiva que coincida con la tarea:

• La topología de espacio de trabajo, pestaña y panel organiza las ubicaciones de las terminales.
• Los comandos de panel controlan terminales sin procesar, shells, pruebas, servidores, entrada y salida.
• Los comandos de agente controlan el agente de codificación reconocido que ocupa actualmente un panel.

Un panel existe incluso si no contiene un agente. agent start requiere un panel de shell existente y disponible y nunca crea, divide ni mueve el diseño. Usa comandos de panel para procesos ordinarios. Usa comandos de agente cuando Herdr deba validar la identidad del agente o interpretar los estados del ciclo de vida idle, working, blocked, done y unknown.

Los comandos de agente aceptan un nombre de agente activo único o el ID del panel que actualmente aloja a ese agente. No aceptan IDs de terminal ni etiquetas simples de tipo de agente. Los nombres deben coincidir con [a-z][a-z0-9_-]{0,31} y ser únicos entre los agentes activos. Un nombre sigue al ocupante actual del panel y se borra cuando ese agente sale, se libera o es reemplazado.

idle significa que el agente está listo para recibir entrada y su pestaña ha sido vista en la interfaz de usuario enfocada de Herdr. done es el mismo estado subyacente de inactividad después de que finaliza el trabajo en segundo plano no visto. Enfocar la pestaña o apuntar al panel o agente con un comando de enfoque lo marca como visto. Las lecturas de la CLI no lo marcan como visto. blocked significa que Herdr reconoció una interfaz de aprobación o pregunta. unknown significa que hay un agente presente pero Herdr no puede clasificarlo con confianza; no prueba la finalización.

Usa IDs y contexto del llamante

Los IDs públicos son identificadores estables opacos:

• workspace: w1
• tab: w1:t1
• pane: w1:p1

Los IDs de pestañas y paneles cerrados no se reutilizan. Un panel movido a otro espacio de trabajo recibe un nuevo ID de panel calificado por espacio de trabajo. Después de pane move, continúa con .result.move_result.pane.pane_id o el nombre del agente activo. El valor antiguo se reporta como .result.move_result.previous_pane_id; solo el contexto del llamante heredado del proceso movido sigue resolviendo ese ID antiguo, así que no lo uses como objetivo general del agente.

Herdr inyecta el contexto del llamante en cada panel administrado:

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

Prefiere --current cuando un comando de panel deba apuntar al panel que llama. Omitir un objetivo puede usar el panel enfocado en la interfaz de usuario, que puede pertenecer al usuario o a otro cliente.

Descubre el estado activo con:

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

Las respuestas de creación exponen los IDs a usar a continuación. workspace create devuelve .result.workspace, .result.tab y .result.root_pane. tab create devuelve .result.tab y .result.root_pane. pane split devuelve el nuevo panel como .result.pane.

Inicia y coordina un agente

Por defecto, usa un panel hermano en la pestaña actual y el directorio de trabajo actual. No crees un espacio de trabajo, pestaña, árbol de trabajo o directorio de trabajo diferente a menos que el usuario lo solicite explícitamente.

Respeta la dirección solicitada por el usuario. De lo contrario, inspecciona el panel llamante:

herdr pane layout --pane "$HERDR_PANE_ID"

Divide un panel ancho hacia la derecha y un panel estrecho o alto hacia abajo. Evita divisiones repetidas en la misma dirección que creen columnas demasiado estrechas o filas cortas. Mantén el foco del usuario en el panel llamante y preserva explícitamente el directorio de trabajo del llamante:

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Reemplaza right con down cuando sea apropiado. Lee el ID del nuevo panel de .result.pane.pane_id.

Un panel de shell disponible debe estar en su prompt interactivo, con el shell mismo en primer plano y sin ningún comando en primer plano, editor o agente en ejecución. Inicia un agente compatible en ese panel con un nombre único útil:

herdr agent start reviewer --kind codex --pane <returned-pane-id>

Usa el tipo solicitado por el usuario. Ejecuta herdr agent para inspeccionar la lista de tipos instalados y las opciones. Pasa argumentos nativos del agente solo después de --:

herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>

agent start regresa solo después de que Herdr detecta el agente esperado en el mismo panel y lo considera listo para entrada interactiva. Por defecto, tiene un tiempo de espera de inicio de 30 segundos.

Envía trabajo a través de la superficie del agente:

herdr agent prompt reviewer "Revisa el diff actual y reporta solo hallazgos accionables." --wait --timeout 120000

agent prompt envía atómicamente el texto y Enter codificado, respetando el modo de pegado entre corchetes activo del panel. Para trabajo normal de agente, --wait es suficiente: espera el primer estado establecido idle, done o blocked. No repitas esos valores predeterminados con --until.

Un prompt enviado desde un estado no activo debe producir un cambio de ciclo de vida observado dentro de cinco segundos. De lo contrario, Herdr devuelve agent_prompt_stalled en lugar de esperar indefinidamente. Esta espera rastrea el estado del ciclo de vida, no un turno individual; si el agente ya está trabajando, la finalización del turno activo puede satisfacerlo.

Usa --until solo para un flujo de trabajo específico de estado, como esperar a que un agente ya en ejecución solicite entrada:

herdr agent wait reviewer --until blocked --timeout 120000

Sin --until, agent wait independiente usa los mismos valores predeterminados de estado establecido que agent prompt --wait.

Usa teclas lógicas para los controles interactivos de la interfaz de usuario del agente:

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr valida todas las teclas antes de escribir cualquier byte. Lee el resultado a través del agente resuelto:

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

Si una espera falla o devuelve blocked, inspecciona agent get y agent read antes de decidir qué entrada enviar. Usa la superficie del panel solo cuando el control de terminal sin procesar sea intencional.

Ejecuta un comando ordinario en otro panel

Crea un panel hermano con la misma regla de geometría, preserva el directorio de trabajo del llamante y mantén el foco del usuario sin cambios:

herdr pane split --current --direction right --cwd "$PWD" --no-focus

Lee el ID del nuevo panel de .result.pane.pane_id, luego ejecuta e inspecciona el comando:

herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "resultado de prueba" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

pane run envía atómicamente el texto del comando y Enter. pane wait-output busca la instantánea seleccionada inmediatamente, por lo que la salida que ya existe puede coincidir. Usa --match <texto> para una subcadena literal o --regex <patrón> para una expresión regular de Rust. Omitir --timeout permite una espera indefinida.

Usa la fuente de lectura que coincida con la tarea:

• visible: el viewport actualmente renderizado.
• recent: salida renderizada reciente, incluyendo ajustes de línea suaves.
• recent-unwrapped: salida reciente con ajustes de línea suaves unidos; prefíerelo para registros y transcripciones.
• detection: la instantánea del búfer inferior de texto plano utilizada para la detección de agentes.

Usa --format ansi cuando los colores y el estilo de terminal sean evidencia. De lo contrario, usa texto.

--lines le pide a Herdr más filas de la pantalla disponible del panel y del historial de desplazamiento del host. Si aumentarlo no revela más de una respuesta completa, es probable que el panel esté ejecutando el agente en la pantalla alternativa de la terminal. Las filas que salen de la pantalla alternativa no ingresan al historial de desplazamiento del host de Herdr, por lo que un recuento de líneas mayor no puede recuperarlas.

Después de esa lectura fallida, pídele al agente que escriba su respuesta completa como Markdown en un directorio temporal y que responda solo con la ruta del archivo, luego lee el archivo directamente. Usa esto solo como recurso de respaldo; no solicites salida de archivo en el prompt inicial.

Reglas de seguridad y coordinación

• Usa --no-focus para trabajo en segundo plano a menos que el usuario haya solicitado cambiar de contexto.
• Usa --current, un ID de panel explícito o un nombre de agente único. No confíes en el panel enfocado de otro cliente.
• Analiza los IDs de las respuestas JSON. No los derives del orden de la barra lateral ni de ejemplos.
• No cierres espacios de trabajo, pestañas, paneles o sesiones que no hayas creado a menos que el usuario lo solicite explícitamente.
• Nunca ejecutes herdr server stop desde una sesión activa a menos que el usuario tenga la intención explícita de detener el servidor y sus procesos de panel.
• Nunca mates el proceso principal de Herdr. Usa sesiones de prueba con nombre para experimentos que necesiten un servidor aislado.
• Los errores del servidor CLI son JSON en stderr con código de salida 1. Los errores de sintaxis CLI salen con código de salida 2.

Modismos locales

La compuerta HERDR_ENV=1 anterior se aplica a controlar la sesión actual desde dentro de un panel. El trabajo a nivel de host — editar configuración, instalar plugins, depurar la detección de agentes, construir automatización alrededor del socket/CLI — es legítimo desde cualquier terminal. Para esas tareas, lee references/local-idioms.md: configuración de entrega de notificaciones, mantenimiento de detección de agentes, metadatos de la barra lateral desde hooks de Claude Code, patrones de suscripción a eventos, flujo de worktree y notas sobre creación de plugins.