# Herdr > Controla Herdr, un multiplexor de terminal para agentes de código; úsalo solo cuando el usuario mencione Herdr explícitamente. Requiere HERDR_ENV=1. Fuente: https://skillsagentes.com/skills/herdrdev/herdr/herdr Markdown: https://skillsagentes.com/skills/herdrdev/herdr/herdr.md Repositorio: https://github.com/herdrdev/herdr Autor: herdrdev Licencia: Apache-2.0 Actualizado: ayer Coste de contexto: 82 tok instalada, 2.5k tok al activarse, 2.5k tok con todos los archivos del bundle Bundle: 1 archivo, 10 KB Permisos que pide: ninguno declarado ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add herdrdev/herdr --skill herdr --agent claude-code # Cursor npx -y skills add herdrdev/herdr --skill herdr --agent cursor # Codex npx -y skills add herdrdev/herdr --skill herdr --agent codex # Gemini CLI npx -y skills add herdrdev/herdr --skill herdr --agent gemini # Windsurf npx -y skills add herdrdev/herdr --skill herdr --agent windsurf # Cline npx -y skills add herdrdev/herdr --skill herdr --agent cline ``` ## Qué hace - Le da al agente comandos `herdr` para inspeccionar y controlar workspaces, tabs, panes y otros agentes dentro de Herdr - Permite crear panes hermanos, ejecutar comandos en ellos y leer su salida - Permite iniciar y coordinar otro agente (agent start/prompt/wait/send-keys) en un pane disponible - Define reglas de seguridad como usar --no-focus, no cerrar sesiones ajenas y no matar el proceso principal de Herdr ## Cuándo usarla - El usuario menciona explícitamente Herdr o pide usar Herdr para inspeccionar o controlar panes, tabs, workspaces, comandos u otro agente ## Cuándo no - No usar solo porque una tarea podría beneficiarse de una terminal en segundo plano, delegación o trabajo paralelo - No usar si HERDR_ENV no está definido como 1 (el agente no está corriendo dentro de Herdr) ## Qué la activa - "Usa Herdr para abrir un pane nuevo y correr los tests" - "Con Herdr, inicia un agente codex en un pane disponible y pídele que revise el diff" - "Herdr, muéstrame el estado de los agentes activos en este workspace" - "Divide el pane actual con Herdr y ejecuta 'just test' en el nuevo" ## Antes de instalar - Requiere que el entorno tenga HERDR_ENV=1 y el binario `herdr` disponible en PATH. - Variables de entorno: HERDR_ENV, HERDR_PANE_ID, HERDR_TAB_ID, HERDR_WORKSPACE_ID - reads environment config ## Archivos - SKILL.md — 10 KB ## SKILL.md Reproducido tal cual desde herdrdev/herdr bajo Apache-2.0. Esta sección es el documento original y está en inglés. # Herdr Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding agents running inside panes, and exposes the current session through the `herdr` CLI. Before issuing any control command, verify that this agent is running inside a Herdr-managed pane: ```bash test "${HERDR_ENV:-}" = 1 ``` If the check fails, say that you are not running inside Herdr and stop. Do not inspect or control the focused Herdr session from outside Herdr. When the check passes, the `herdr` binary in `PATH` talks to the current session. Use it to inspect neighboring work, create terminal layout, start agents and commands, read output, and wait for state changes. ## Learn the current CLI The installed binary is the authority for command syntax. Start with: ```bash herdr --help ``` Then print the relevant command group by running the group without a subcommand: ```bash herdr agent herdr pane herdr workspace herdr tab herdr worktree herdr terminal herdr notification herdr integration herdr session ``` Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments. Commands such as `herdr workspace create` are valid with defaults and will execute. Most control commands return JSON. Read identifiers and state from those responses instead of predicting them. ## Understand layout, panes, and agents Choose the primitive that matches the job: - Workspace, tab, and pane topology organize terminal locations. - Pane commands control raw terminals, shells, tests, servers, input, and output. - Agent commands control the recognized coding agent currently occupying a pane. A pane exists whether or not it contains an agent. `agent start` requires an existing available shell pane and never creates, splits, or moves layout. Use pane commands for ordinary processes. Use agent commands when Herdr must validate agent identity or interpret `idle`, `working`, `blocked`, `done`, and `unknown` lifecycle states. Agent commands accept either a unique live agent name or the pane ID currently hosting that agent. They do not accept terminal IDs or bare agent-kind labels. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. A name follows the current pane occupant and is cleared when that agent exits, is released, or is replaced. `idle` means the agent is ready for input and its tab has been seen in the focused Herdr UI. `done` is the same underlying idle state after unseen background work finishes. Focusing the tab or targeting the pane or agent with a focus command marks it seen. CLI reads do not mark it seen. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify it confidently; it does not prove completion. ## Use IDs and caller context Public IDs are opaque stable handles: - workspace: `w1` - tab: `w1:t1` - pane: `w1:p1` Closed tab and pane IDs are not reused. A pane moved into another workspace receives a new workspace-qualified pane ID. After `pane move`, continue with `.result.move_result.pane.pane_id` or the live agent name. The old value is reported as `.result.move_result.previous_pane_id`; only the moved process's inherited caller context keeps resolving that old ID, so do not use it as a general agent target. Herdr injects the caller's context into each managed pane: ```bash printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID" ``` Prefer `--current` when a pane command should target the calling pane. Omitting a target may use the UI-focused pane, which can belong to the user or another client. Discover live state with: ```bash herdr workspace list herdr tab list --workspace "$HERDR_WORKSPACE_ID" herdr pane current --current herdr pane list --workspace "$HERDR_WORKSPACE_ID" herdr agent list ``` Creation responses expose the IDs to use next. `workspace create` returns `.result.workspace`, `.result.tab`, and `.result.root_pane`. `tab create` returns `.result.tab` and `.result.root_pane`. `pane split` returns the new pane as `.result.pane`. ## Start and coordinate an agent Default to a sibling pane in the current tab and the current working directory. Do not create a workspace, tab, worktree, or different cwd unless the user explicitly requests that topology or location. Honor a direction requested by the user. Otherwise inspect the caller pane: ```bash herdr pane layout --pane "$HERDR_PANE_ID" ``` Split a wide pane to the right and a narrow or tall pane down. Avoid repeated same-direction splits that create unusably narrow columns or short rows. Keep the user's focus in the calling pane and explicitly preserve the caller's working directory: ```bash herdr pane split --current --direction right --cwd "$PWD" --no-focus ``` Replace `right` with `down` when appropriate. Read the new pane ID from `.result.pane.pane_id`. An available shell pane must be at its interactive prompt, with the shell itself in the foreground and no foreground command, editor, or agent running. Start a supported agent in that pane with a useful unique name: ```bash herdr agent start reviewer --kind codex --pane ``` Use the kind requested by the user. Run `herdr agent` to inspect the installed kind list and options. Pass native agent arguments only after `--`: ```bash herdr agent start reviewer --kind codex --pane -- ``` `agent start` returns only after Herdr detects the expected agent in the same pane and considers it ready for interactive input. It defaults to a 30-second startup timeout. Submit work through the agent surface: ```bash herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000 ``` `agent prompt` atomically submits text and encoded Enter while honoring the pane's live bracketed-paste mode. For normal agent work, `--wait` is enough: it waits for the first settled `idle`, `done`, or `blocked` state. Do not repeat those defaults with `--until`. A prompt sent from a non-working state must produce an observed lifecycle change within five seconds. Otherwise Herdr returns `agent_prompt_stalled` instead of waiting indefinitely. This wait tracks lifecycle state, not an individual turn; if the agent is already working, completion of the active turn may satisfy it. Use `--until` only for a state-specific workflow, such as waiting for an already-running agent to request input: ```bash herdr agent wait reviewer --until blocked --timeout 120000 ``` Without `--until`, standalone `agent wait` uses the same settled-state defaults as `agent prompt --wait`. Use logical keys for interactive agent UI controls: ```bash herdr agent send-keys reviewer esc herdr agent send-keys reviewer ctrl+c ``` Herdr validates all keys before writing any bytes. Read the result through the resolved agent: ```bash herdr agent get reviewer herdr agent read reviewer --source recent-unwrapped --lines 120 ``` If a wait fails or returns `blocked`, inspect `agent get` and `agent read` before deciding what input to send. Use the pane surface only when raw terminal control is intentional. ## Run an ordinary command in another pane Create a sibling pane with the same geometry rule, preserve the caller's working directory, and keep user focus unchanged: ```bash herdr pane split --current --direction right --cwd "$PWD" --no-focus ``` Read the new pane ID from `.result.pane.pane_id`, then run and inspect the command: ```bash herdr pane run "just test" herdr pane wait-output --match "test result" --timeout 120000 herdr pane read --source recent-unwrapped --lines 120 ``` `pane run` atomically sends command text and Enter. `pane wait-output` searches the selected snapshot immediately, so output that already exists can match. Use `--match ` for a literal substring or `--regex ` for a Rust regular expression. Omitting `--timeout` allows an indefinite wait. Use the read source that matches the task: - `visible`: the currently rendered viewport. - `recent`: recent rendered output, including soft wraps. - `recent-unwrapped`: recent output with soft wraps joined; prefer it for logs and transcripts. - `detection`: the plain-text bottom-buffer snapshot used for agent detection. Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text. `--lines` asks Herdr for more rows from the pane's available screen and host scrollback. If increasing it does not reveal more of a completed response, the pane is probably running the agent on the terminal's alternate screen. Rows that leave the alternate screen do not enter Herdr's host scrollback, so a larger line count cannot recover them. After that failed read, ask the agent to write its complete response as Markdown in a temporary directory and reply only with the file path, then read the file directly. Use this only as a fallback; do not request file output in the initial prompt. ## Safety and coordination rules - Use `--no-focus` for background work unless the user asked to switch context. - Use `--current`, an explicit pane ID, or a unique agent name. Do not rely on another client's focused pane. - Parse IDs from JSON responses. Do not derive them from sidebar order or examples. - Do not close workspaces, tabs, panes, or sessions you did not create unless the user explicitly asked. - Never run `herdr server stop` from an active session unless the user explicitly intends to stop the server and its pane processes. - Never kill the main Herdr process. Use named test sessions for experiments that need an isolated server. - CLI server errors are JSON on stderr with exit status 1. CLI syntax errors exit with status 2. ## Dónde encaja - Categoría: [Herramientas para desarrolladores](https://skillsagentes.com/categorias/herramientas-desarrollo.md) — Skills que cambian cómo tu agente escribe, revisa y despliega código. - Creador: [herdrdev](https://skillsagentes.com/creators/herdrdev.md) — 0 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Herdr Pre Release Audit](https://skillsagentes.com/skills/herdrdev/herdr/herdr-pre-release-audit.md): Audita la preparación del release de herdr comparando commits desde la base de release con el changelog y la documentación de docs/next. - [Triage](https://skillsagentes.com/skills/herdrdev/herdr/triage.md): Hace triage de los issues abiertos de GitHub de herdr en una tabla Markdown concisa y orientada a decisiones, con luces de prioridad. - [Herdr Throwaway Repro](https://skillsagentes.com/skills/herdrdev/herdr/herdr-throwaway-repro.md): Crea y controla una sesión Herdr desechable con nombre único desde otra sesión Herdr. Para reproducciones aisladas de runtime, pane, terminal, proceso, API, persistencia o agente vía CLI/API. - [Writing Commit Messages](https://skillsagentes.com/skills/herdrdev/herdr/writing-commit-messages.md): Escribe mensajes de commit de Git. Se activa cuando el usuario pide escribir o redactar un mensaje de commit, o algo similar. ## Skills relacionadas - [Writing Commit Messages](https://skillsagentes.com/skills/herdrdev/herdr/writing-commit-messages.md): Escribe mensajes de commit de Git. Se activa cuando el usuario pide escribir o redactar un mensaje de commit, o algo similar. - [Orca Emulator Android](https://skillsagentes.com/skills/stablyai/orca/orca-emulator-android.md): Controla un emulador o dispositivo Android desde Orca con el CLI `orca`: AVDs, taps, swipes, tecleo, botones físicos, rotación, apps, permisos, árbol de accesibilidad y logcat. - [Orca Emulator](https://skillsagentes.com/skills/stablyai/orca/orca-emulator.md): Controla un emulador/simulador móvil (iOS) desde Orca con la CLI `orca`: taps, gestos, tipeo, botones, cámara, permisos y árbol de accesibilidad, viendo la vista en vivo en Orca. - [Orca Cli](https://skillsagentes.com/skills/stablyai/orca/orca-cli.md): Usa el CLI público `orca` para gestionar worktrees, contextos de carpeta, terminales, repos, automations, artifacts, comentarios de worktree y el navegador embebido de la app Orca. - [Linear Tickets](https://skillsagentes.com/skills/stablyai/orca/linear-tickets.md): Alias antiguo (legacy) del paquete para orca-linear; usa la CLI Linear de Orca vía orca linear ... para leer contexto de tickets, publicar avances, mover estados, adjuntar links de PR/MR y triagear tareas. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)