# Herdr Guide > Control Herdr, a terminal multiplexer for coding agents. Use when the user asks to inspect or control panes, tabs, workspaces, terminals, commands, sessions, or communication with another agent, and whenever an orchestrating skill such as foreman-agent needs the Herdr CLI. This skill owns Herdr CLI mechanics; it does not own task backlog policy. Requires HERDR_ENV=1. - Skill: `phananhtuan09/herdr-guide` (Agent Skill) - Install (CLI): `npx skillmds@latest add phananhtuan09/herdr-guide` - Raw SKILL.md: https://api.skillmd.com/api/skills/phananhtuan09/herdr-guide/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: phananhtuan09 (https://skillmd.com/u/phananhtuan09) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/phananhtuan09/herdr-guide --- # Herdr Herdr is a terminal multiplexer and runtime for coding agents. It organizes terminals into workspaces, tabs, and panes, detects agent identity and status, and exposes the running session through the `herdr` CLI. This skill owns Herdr mechanics only: which command to run, which target to address, how to read the response. It does not own what work should be dispatched or how a backlog is tracked. Use `foreman-agent` for backlog policy, task assignment decisions, and reporting to the human; it loads this skill for the mechanics. Before issuing any control command, check 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 running session. Use it to inspect neighboring work, create isolated terminal contexts, start agents and commands, read their output, and wait for state changes. ## Learn the current CLI The installed binary is the authority for command syntax. Begin with: ```bash herdr --help ``` Then print the relevant command group by running it without a subcommand: ```bash herdr agent herdr pane herdr workspace herdr worktree herdr tab herdr terminal herdr notification herdr integration herdr session ``` Command groups change between releases. Print the group before using it rather than trusting an example in this file. Do not run bare `herdr` for discovery; it launches or attaches the TUI. Do not probe a mutating nested command by omitting arguments; some commands, including `herdr workspace create`, are valid with defaults and will execute. Use the command-group output above instead. Most control commands print JSON. Read identifiers and state from those responses instead of predicting either one. ## IDs and current context Public IDs are short stable handles: - workspace: `w1` - tab: `w1:t1` - pane: `w1:p1` - terminal: `term_...` The encoded suffix can contain letters and can grow beyond one character. Treat every ID as an opaque string. Closed tab and pane IDs are not reused and do not retarget later resources. A pane moved into another workspace receives a new public pane ID. Re-read create, split, move, list, or get responses after mutations; never construct an ID from a workspace or display number. Herdr injects the caller's stable context into every 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 can use the UI-focused pane, which may 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" ``` ## Control agents through panes An agent runs inside a pane. Use the pane ID as the control target for agents, shells, servers, tests, and logs. This keeps spawning, input, reads, waits, and cleanup on one stable control surface. The `herdr agent` group addresses agents directly and is the cheaper surface when you care about the agent rather than the terminal: ```bash herdr agent list herdr agent get herdr agent prompt "" [--wait --until working --timeout 30000] herdr agent read --source recent-unwrapped --lines 120 herdr agent wait --until idle --timeout 120000 herdr agent rename ``` A target is a unique agent name or a pane ID that currently hosts an agent. `herdr agent list` returns one record per agent with `agent`, `agent_status`, `cwd`, `pane_id`, `tab_id`, `workspace_id`, and `terminal_id`, so a single call answers which agents exist, what they are doing, and where they live. Pane IDs change when a pane moves; `terminal_id` does not. Name an agent with `herdr agent rename` when something must address it durably across moves and restarts. Use workspace and tab commands for organization. Use worktree commands only when you intentionally want Herdr to create, open, or remove a Git checkout. Pane records expose `agent`, `agent_status`, and native session metadata when available. Agent status is `idle`, `working`, `blocked`, `done`, or `unknown`. `idle` and `done` are the same underlying semantic state with different attention state: - `idle`: the agent is waiting and its result is considered seen. - `done`: the agent finished and its result has not been seen. An agent that first opens at its prompt reports `idle`, including in a background pane. After a working or blocked agent completes, it reports `done` when its tab or workspace is in the background. It reports `idle` when it completes in the active tab while the foreground client is focused. If the foreground client is explicitly unfocused, completion can become `done` even in the active tab. Focusing a pane, switching to its tab, or regaining outer terminal focus marks the visible tab as seen, so `done` becomes `idle`. Switching away does not turn an existing `idle` status into `done`; `done` is created by a later completion while the pane is unseen. With no foreground client, a new completion in the globally active tab is treated as seen while completions in background tabs still become `done`. ## Start agents interactively Default to a sibling pane in the current tab and 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's current rectangle: ```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 would create unusably narrow columns or short rows. Keep the user's focus in the calling pane: ```bash herdr pane split --current --direction right --no-focus ``` Replace `right` with `down` when the layout calls for it. Read `result.pane.pane_id` from the JSON response. Give the pane a useful label, then start the requested agent by running only its normal executable so its interactive TUI opens: ```bash herdr pane rename "reviewer" herdr pane run "codex" ``` Use the executable that belongs to the requested agent: - Codex: `codex` - Claude Code: `claude` - pi: `pi` - OpenCode: `opencode` - OMP: `omp` Do not pass the task as an argv prompt by default. Do not add non-interactive flags. Only change the normal interactive launch when the user explicitly asks for a different launch mode or command. Inspect the pane after launch. If `agent_status` is not yet `idle`, wait for the idle transition. Once it is idle, submit the task with `pane run`: ```bash herdr pane get herdr agent wait --until idle --timeout 30000 herdr pane run "Review the current diff and report only actionable findings." ``` Status waits match the current status immediately or wait for a future matching transition. `pane run` sends the text and Enter together. Use it for initial prompts and follow-ups instead of coordinating `send-text` and `send-keys` separately. For normal background work, wait for the agent to start working. If the pane remains in a background tab or workspace, wait for `done` before reading its transcript: ```bash herdr agent wait --until working --timeout 30000 herdr agent wait --until done --timeout 120000 herdr pane read --source recent-unwrapped --lines 120 ``` If the user is watching that tab, completion reports `idle` instead, so wait for `idle`. Always treat either `idle` or `done` as completed when inspecting `pane get`; the difference is whether the result has been seen. If a wait times out, inspect `herdr pane get ` and `pane read` before deciding what to do. A `blocked` agent needs input; an `unknown` pane may not yet contain a detected or integrated agent. Submit follow-ups the same way: ```bash herdr pane run "Now check the failing test." ``` ## Run an ordinary command in another pane Split the calling pane using the same geometry rule without moving the user's focus: ```bash herdr pane split --current --direction right --no-focus ``` Read the new `pane_id` from the JSON response, 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 ``` Inspect existing output before waiting for future output. A wait timeout exits with status `1`. Use the read source that matches the task: - `visible`: the current rendered viewport - `recent`: recent scrollback as rendered, including soft wraps - `recent-unwrapped`: recent scrollback with soft wraps joined; prefer it for logs and transcripts - `detection`: the bottom-buffer snapshot used by agent detection Use `--format ansi` when colors and terminal styling are evidence. Otherwise use text. If the user explicitly asks for another tab, workspace, or worktree, discover that command group and use returned IDs. Do not infer a larger topology from a request to start an agent or command. ## Safety and coordination rules - Use `--no-focus` for background work unless the user asked to switch context. - Use `--current` or an explicit ID. Do not rely on another client's focused pane. - Parse IDs from JSON responses. Do not derive them from sidebar order or examples. - Inspect before waiting. Read current output first, then wait for the next state or output you expect. - 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.