This is the full developer documentation for Herdr # Herdr documentation > Install, learn, and configure Herdr. Start on the path that matches you — no multiplexer experience required. ## Pick your path [Section titled “Pick your path”](#pick-your-path) New to terminal multiplexers? You don’t need to learn shortcuts to start. Herdr is mouse-first: click panes, drag borders, split and switch from right-click menus. [Quick start →](/docs/quick-start/) Coming from tmux or zellij? You already know the model. The prefix is `ctrl+b`, panes persist, detach and reattach work the way you expect. [Concepts →](/docs/concepts/) · [Keybindings →](/docs/configuration/#keybindings) ## Or let your agent introduce you [Section titled “Or let your agent introduce you”](#or-let-your-agent-introduce-you) If you already run an AI coding agent, let it handle the onboarding. Paste this prompt: ```text Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step. ``` The guide covers Herdr’s concepts, setup, configuration, and common fixes, so your agent can answer from the docs instead of improvising. ## Core guides [Section titled “Core guides”](#core-guides) Agents See supported agents, detection behavior, integrations, custom labels, and direct attach. [Understand agents →](/docs/agents/) Connecting machines Keep Local and saved SSH machines in one window, with a combined agent list and independent reconnects. [Connect your machines →](/docs/connecting-machines/) Session state Understand detach, restart restore, pane history replay, native agent resume, and live handoff. [Compare state paths →](/docs/session-state/) Configuration Configure keybindings, themes, sidebar behavior, notifications, scrollback, and advanced options. [Configure Herdr →](/docs/configuration/) API Control Herdr from scripts, tools, and agents through the CLI and local socket API. [Read the API guide →](/docs/socket-api/) Plugins Author local executable workflow plugins with manifest actions and event hooks. [Write a plugin →](/docs/plugins/) Marketplace Share plugins from GitHub today and tag your repo to be listed when the marketplace launches. [Publish a plugin →](/docs/marketplace/) # Add Herdr support to your agent > Report your coding agent's state and resume command to Herdr from your own code, without adding native support to Herdr. If you build a coding agent, you can make it a first-class citizen in Herdr from your own code. You don’t need a pull request to Herdr, and you don’t need to wait for a Herdr release. Once your agent reports to Herdr, users get: * your agent’s name and `idle`, `working`, or `blocked` state in the sidebar and in `herdr agent list` * notifications when it finishes or needs a decision * `herdr agent wait` and other automation that waits on agent state * the same session back in the same pane after a Herdr server restart Herdr owns the integrations for agents whose vendors don’t ship one. If you maintain your agent, owning the integration yourself means you can fix it on your own release schedule. ## How it works [Section titled “How it works”](#how-it-works) Every process in a Herdr pane inherits these environment variables: | Variable | Meaning | | ------------------- | ------------------------------------ | | `HERDR_ENV` | `1` inside Herdr | | `HERDR_PANE_ID` | The pane your agent runs in | | `HERDR_BIN_PATH` | The Herdr binary that owns this pane | | `HERDR_SOCKET_PATH` | Herdr’s API socket | Your agent makes three kinds of reports through `"$HERDR_BIN_PATH"`: 1. **State.** Report `idle`, `working`, or `blocked` whenever it changes. 2. **Resume command.** Report the command that reopens the current session. 3. **Release.** Release the pane when your agent exits. Only report when `HERDR_ENV=1` and the other variables are set. Outside Herdr, your integration should do nothing. ## Report state [Section titled “Report state”](#report-state) ```bash "$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ --source my-agent \ --agent my-agent \ --state working \ --seq 1 ``` * Report `working` when a turn starts, `idle` when your agent is ready for input, and `blocked` when it needs the user to decide something. Add `--message` to explain a block. * `--agent` is the name users see. Use your own agent’s name, not the name of an agent Herdr already supports. * `--source` identifies your integration. Keep it stable and unique. Don’t start it with `herdr:`, because Herdr’s own integrations use that prefix. * `--seq` is optional but recommended. It must increase with every report from your source, including across sessions and restarts of your agent. A timestamp works well. Herdr ignores reports whose number is not higher than the last one it accepted, so late or out-of-order reports can’t overwrite newer state. To change how your agent appears without changing its state, such as a title or custom status text, see [Custom status labels](/docs/integrations/#custom-status-labels). ## Report the resume command [Section titled “Report the resume command”](#report-the-resume-command) Put the command that resumes the current session after `--`. Include the options that session needs, such as the model or permission mode, so the resumed session behaves the same: ```bash "$HERDR_BIN_PATH" pane report-agent "$HERDR_PANE_ID" \ --source my-agent \ --agent my-agent \ --state idle \ --seq 2 \ --agent-session-id "$SESSION_ID" \ -- my-agent --resume "$SESSION_ID" --model my-model ``` You can attach the command to any state report, or send it with `pane report-agent-session` when only the session changes. Report it again whenever your agent switches sessions. After a Herdr server restart, Herdr opens the pane in the same directory and runs that command there. The command must follow these rules: * The first word is a plain command name on the user’s `PATH`, such as `my-agent`, not a path. * No argument contains an apostrophe or a control character. * At most 64 arguments and 8 KiB in total. * Your source must hold the pane first, so send a state report with `report-agent` before or along with the command. Otherwise Herdr answers with `resume_not_accepted`. Herdr rejects a command that breaks the first three rules with `invalid_resume_argv` and does not apply that report. Users can turn off resume with `[session] resume_agents_on_restore = false`. ## Release on exit [Section titled “Release on exit”](#release-on-exit) ```bash "$HERDR_BIN_PATH" pane release-agent "$HERDR_PANE_ID" \ --source my-agent \ --agent my-agent \ --seq 3 ``` Releasing clears your agent’s name, state, and resume command from the pane right away. Only release when the user actually quits. If your agent replaces one session with another in the same process, report the new session instead of releasing. If your agent exits without releasing, Herdr notices once the pane is back at its idle shell prompt and clears the agent and its resume command. This usually takes a second or two. It is a safety net, not a replacement for releasing. ## Keep it out of the way [Section titled “Keep it out of the way”](#keep-it-out-of-the-way) * Don’t let Herdr slow your agent down. Send reports in the background or with a short timeout, and ignore failures. * Send only the latest state. If several changes queue up while a report is in flight, drop the older ones. * Resume commands need Herdr 0.9.2 or later. Older versions ignore them, so state reports and release keep working there. ## Use the socket directly [Section titled “Use the socket directly”](#use-the-socket-directly) `HERDR_BIN_PATH` and the CLI are the portable choice, including on Windows. If your agent needs direct IPC, send the equivalent `pane.report_agent`, `pane.report_agent_session`, and `pane.release_agent` requests described in the [Socket API](/docs/socket-api/#agent-state-reporting). The resume command goes in the `resume_argv` array. ## Check your integration [Section titled “Check your integration”](#check-your-integration) Start your agent in a Herdr pane, then check what Herdr sees: ```bash herdr pane get "$HERDR_PANE_ID" herdr agent list ``` To test restore without touching your normal session, use a separate named session: 1. Start `herdr --session my-agent-test`, then run your agent in a pane. 2. Stop that session with `herdr session stop my-agent-test`. 3. Start `herdr --session my-agent-test` again. The pane should run your resume command and your agent should report again. # Agent automation > Use Herdr's layout, pane, and agent primitives to coordinate coding agents from scripts or other agents. Use Herdr as an automation layer for coding agents. A script can control them, or one agent can create work for other agents, inspect their state, and collect their results. Choose the primitive that matches the job. ## Three primitives [Section titled “Three primitives”](#three-primitives) | Primitive | Responsibility | | ---------------------------------------------- | ----------------------------------------------------------------------------------- | | Layout (`workspace`, `tab`, and pane topology) | Create and organize terminal locations. | | Pane | Control a raw terminal: run commands, send input, read output, and wait for output. | | Agent | Control a recognized coding agent by name or pane and lifecycle state. | A pane exists whether or not it contains an agent. An agent is the recognized process currently running inside a pane. `agent start` therefore requires an existing shell pane and never creates, splits, or moves layout. Creating a workspace also creates its first tab and root pane; creating a tab creates its root pane. Use the returned pane ID for the first process, and split only when that layout needs another terminal. Creation commands print JSON. Capture IDs from the response instead of predicting them: ```bash created=$(herdr workspace create --cwd ~/project --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` 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`. Moving a pane to another workspace changes its workspace-qualified pane ID. After any `pane move`, continue with `.result.move_result.pane.pane_id`; the response keeps the old value at `.result.move_result.previous_pane_id`. A running process keeps its launch-time Herdr environment, but the old `HERDR_PANE_ID` remains an alias for that terminal, so `--current` stays safe. New commands can still resolve the agent by name after the move, but a wait already in progress ends with `agent_not_running`. Use pane commands for shells, tests, servers, CI watchers, and other ordinary terminal processes. Use agent commands when Herdr needs to understand which agent is running or whether it is `working`, `blocked`, `done`, `idle`, or `unknown`. ## Agent identity and launch [Section titled “Agent identity and launch”](#agent-identity-and-launch) A pane ID such as `w1:p2` identifies the terminal location. An agent name such as `reviewer` is a convenient alias for the current agent in that pane. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among live agents. The alias is cleared when that agent exits, is released, or is replaced; it does not permanently rename the pane. Agent commands accept either a unique live name or the pane ID that currently hosts the agent. An available shell pane is at its interactive shell prompt: the shell itself owns the foreground, with no foreground command, editor, or agent running. Return the pane to its prompt before calling `agent start`. `--kind` selects a supported agent and its canonical executable. Supported kinds are `pi`, `claude`, `codex`, `gemini`, `cursor`, `devin`, `agy`, `cline`, `omp`, `mastracode`, `opencode`, `copilot`, `kimi`, `kiro`, `droid`, `amp`, `grok`, `hermes`, `kilo`, `qodercli`, `qwen`, `letta`, `maki`, and `muse`. Arguments after `--` are passed unchanged to that executable. Successful `agent start` returns only after Herdr detects the expected agent in the same terminal and marks it ready for interactive input. If detection reports `blocked` during startup, the command returns `agent_not_ready` immediately. The name remains available for `agent read` and `agent send-keys`, and becomes ready for prompts after detection reports `idle`. Startup waits for 30 seconds by default; `--timeout` must be greater than 3000 and no more than 300000 milliseconds. ```bash herdr agent start reviewer --kind codex --pane "$review_pane" -- -m gpt-5.4 ``` Agents launched manually are detected automatically and can be addressed by pane ID. Give one a name when a stable human-readable target is useful: ```bash herdr agent get w1:p2 herdr agent rename w1:p2 reviewer ``` ## Choose the control surface [Section titled “Choose the control surface”](#choose-the-control-surface) | Goal | Command | | ------------------------------------------- | ------------------ | | Run a shell command and submit it | `pane run` | | Send literal text without Enter | `pane send-text` | | Send terminal keys or modifier chords | `pane send-keys` | | Wait for text or a regular expression | `pane wait-output` | | Start a supported agent in an existing pane | `agent start` | | Submit a prompt, optionally waiting for it | `agent prompt` | | Send keys to an agent’s interactive UI | `agent send-keys` | | Wait for agent lifecycle state | `agent wait` | `agent prompt` submits text plus encoded Enter and honors the terminal’s live bracketed-paste mode. It can prompt an agent that is already working. If the agent is already `blocked`, it returns `agent_blocked` without sending terminal input; inspect the dialog and use `agent send-keys` for a deliberate response. Use `agent send-keys` for interactions such as `esc`, `up`, `enter`, or `ctrl+c`; `escape` is accepted as an alias for `esc`. Use the pane input commands when you deliberately want raw terminal control. Pane input addresses the terminal regardless of its current occupant. Agent input resolves the live agent and rejects the operation if that agent no longer controls the pane. `agent prompt --wait` rejects an agent already `blocked` with `agent_blocked`, without sending input or starting a wait. Otherwise, it writes the prompt and delayed Enter as one ordered submission before waiting. On Windows, Codex receives a paste boundary before Enter so submission does not depend on prompt size. The caller timeout includes submission time. If the prompt started from another non-working state, Herdr waits up to five seconds after submission to observe `working` or `blocked`. Otherwise, it returns `agent_prompt_stalled`; if the caller timeout expires first, it returns the normal `timeout` error. This prevents unrelated `idle`, `done`, or session changes from completing the wait. After Herdr observes activity, it waits for the requested settled status. It does not track individual turns. If the agent is already working, completion of that active turn may satisfy the wait. Standalone `agent wait` observes the current agent and returns immediately if its status already matches. Both commands default to `idle`, `done`, or `blocked`. Repeat `--until` to accept several exact states, for example `--until idle --until done`; use `--until unknown` explicitly when needed. On `agent prompt`, `--until` requires `--wait`. `idle` and `done` both mean the agent is ready for input. The CLI/API uses the server’s seen state: `done` is idle but not yet marked seen, explicit `pane focus` / `agent focus` commands mark the target seen, and reads do not. Each TUI client tracks viewed completions independently, so a client’s Done badge can differ from the CLI or another client’s badge. `blocked` means Herdr recognized an approval or question UI. `unknown` means an agent is present but Herdr cannot classify its lifecycle confidently; it does not prove successful completion. Use exact `--until` states when that distinction matters. Startup readiness, restoring an idle conversation, and switching agent conversations do not count as completed work. An agent that starts working immediately can finish its first task without Herdr first seeing an idle prompt. Agent responses may include `completion_seq`, identifying the current idle transition as completed work independently of who has viewed it. It matches that transition’s `state_change_seq`; startup and session changes do not set it. Older servers may omit this field. Clients connected to older servers use observed working states to guard Done badges, so they may miss a turn that starts and finishes between updates. A timeout or `agent_prompt_stalled` does not prove that no input was sent. Read the agent before retrying to avoid submitting the same prompt twice. IDs and agent names are scoped to one server; selecting another machine in the TUI does not retarget CLI commands running in an existing pane. `pane wait-output` does not interpret agent lifecycle. It polls the selected terminal snapshot and searches it immediately, so text that was already present can match. The default source name is `recent`; matching treats that source as unwrapped recent output from the latest 80 rendered terminal rows. `--lines` changes that row limit, and `--regex` uses Rust regular-expression syntax and matches one line at a time. At the CLI, both `pane read` and `agent read` print terminal text directly. The default is UTF-8 text with ANSI escapes stripped; use `--format ansi` or `--ansi` to preserve terminal escapes where the source exposes them. The `detection` source is always plain text. For recent sources, `--lines N` selects the last N rendered terminal rows before optional unwrapping; without it, reads default to 80 rows. For `visible` and `detection`, omitting `--lines` returns the full snapshot, while specifying it keeps the last N newline-delimited lines. The socket API returns the text at `.result.read.text`. ## Alternate-screen history reads [Section titled “Alternate-screen history reads”](#alternate-screen-history-reads) Full-screen agents such as Claude Code and OpenCode render transcript history in the terminal’s alternate screen instead of Herdr’s host scrollback. For an idle, recognized agent at the bottom of its transcript, text reads from `recent` or `recent-unwrapped` automatically use the agent’s mouse-scroll interface when `--lines` requests more than the visible screen. Herdr collects overlapping pages and returns the viewport to the bottom before completing the read. The same behavior applies to `pane read` when the pane contains that agent; it requires no additional option. Other reads remain passive. Herdr does not move the application viewport for `visible`, `detection`, or ANSI reads, output waits and subscriptions, a manually scrolled agent, a direct attachment, or an application that does not report mouse-wheel input. An explicit `agent read --lines N` that needs alternate-screen history returns `agent_not_idle` while the agent is working, blocked, or unknown; wait for idle and retry, or use `--source visible`. Other recent reads return the available screen and host scrollback as before. If a full response is still unavailable, ask the agent to write it as Markdown in a temporary directory and reply only with the file path, then read the file directly. Successful `agent start`, `agent prompt`, and `agent wait` commands return the current agent at `.result.agent`. `pane wait-output` returns `.result.pane_id`, `.result.matched_line`, and the matched snapshot at `.result.read`. Wait commands have no default timeout and can wait indefinitely. On timeout or another server error, CLI commands print a JSON error to stderr and exit with status 1; invalid CLI syntax exits with status 2. ## Recipes [Section titled “Recipes”](#recipes) Start a helper, give it work, and wait for that work to settle: ```bash 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 "Review the current diff" --wait --timeout 120000 herdr agent read reviewer --source recent-unwrapped --lines 120 ``` Wait for an agent to ask for input, inspect it, and interact with its UI: ```bash herdr agent wait reviewer --until blocked --timeout 120000 herdr agent read reviewer --source recent-unwrapped --lines 80 herdr agent send-keys reviewer esc ``` Run an ordinary process and wait for its output without treating it as an agent: ```bash herdr pane run w1:p3 "just test --watch" herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000 ``` See the [CLI reference](/docs/cli-reference/) for the complete command and option list. Shell completions expose the same command tree interactively. # Agent skill file > Install Herdr instructions for Claude Code or another coding agent. Herdr ships a reusable agent skill file at [`skills/herdr/SKILL.md`](https://github.com/herdrdev/herdr/blob/v0.9.3/skills/herdr/SKILL.md). Install that file into any coding agent that supports reusable skills or custom instructions. The skill teaches the agent how to control Herdr from inside a Herdr pane. Herdr also serves a separate guide at [`herdr.dev/agent-guide.md`](https://herdr.dev/agent-guide.md) for a different job: an agent helping a human learn, set up, or troubleshoot Herdr. The skill is for an agent operating Herdr; the guide is for an agent teaching a human. ## What the skill does [Section titled “What the skill does”](#what-the-skill-does) The skill tells an agent to use the `herdr` CLI when `HERDR_ENV=1` is set. That means the agent is running inside a Herdr-managed pane and can safely talk to the local Herdr socket. With the skill installed, an agent can: * inspect workspaces, tabs, panes, and neighboring agents * split panes and run commands without stealing focus * read pane output and recent logs * wait for servers, tests, or another agent to finish * start helper agents in sibling panes The skill is a Markdown instruction file for agents. If Herdr is already installed, run `herdr --skill` to print the release-matched copy bundled with that binary. ## Install it [Section titled “Install it”](#install-it) Install the skill with `npx skills`: ```bash npx skills add herdrdev/herdr --skill herdr -g ``` If you installed the skill while it lived at the repository root, rerun this add command once instead of using `skills update`. The add command replaces the oversized copy and records the new location. The `-g` flag installs it globally for supported agents. Omit `-g` to install it into the current project. Use the repository copy as the manual fallback and source of truth: ```text https://github.com/herdrdev/herdr/blob/v0.9.3/skills/herdr/SKILL.md ``` For agents with a skill system, install that file as a skill named `herdr`. For agents without a skill system, paste the file into the agent’s project or user instructions. After installation, start the agent inside Herdr: ```bash herdr claude ``` Or use any other coding agent in a Herdr pane so `HERDR_ENV=1` is available to the agent process. ## Safety rule [Section titled “Safety rule”](#safety-rule) The skill starts with one guardrail: if `HERDR_ENV=1` is not set, the agent should stop and say it is not running inside a Herdr-managed pane. This prevents an agent outside Herdr from trying to control a session it does not own. ## Agent-facing reference [Section titled “Agent-facing reference”](#agent-facing-reference) The full command guide lives in the skill file itself. It covers pane IDs, `pane split`, `pane run`, `pane read`, `pane wait-output`, `agent wait`, workspace and tab commands, and coordination recipes. Read the source file here: [Open `SKILL.md` on GitHub →](https://github.com/herdrdev/herdr/blob/v0.9.3/skills/herdr/SKILL.md) # Agents > See which coding agents work with Herdr, either supported by Herdr or supporting Herdr themselves, and how agent state works. Herdr is built for running more than one coding agent at a time. Each agent stays in a real terminal pane with its shell, logs, prompts, and running processes intact. Herdr tracks which panes contain agents, rolls their state up to tabs and workspaces, and lets you jump straight to the pane that needs attention instead of polling every terminal by hand. To coordinate agents from scripts or from another agent, see [Agent automation](/docs/agent-automation/). ## Supported agents [Section titled “Supported agents”](#supported-agents) Agents get Herdr support in one of two ways: Herdr supports them, or they support Herdr themselves. Either way you see each agent’s `idle`, `working`, and `blocked` state, get notified when it finishes or needs you, and can wait on it from scripts. Other agents still run normally in Herdr panes. They just show up as plain terminals. ### Supported by Herdr [Section titled “Supported by Herdr”](#supported-by-herdr) Herdr recognizes these agents and reads their state from what they draw on screen. To get the same session back after a Herdr server restart, install the agent’s integration with `herdr integration install `. See [Integrations](/docs/integrations/) for what each one installs. | Agent | Integration | Notes | | ------------------ | ----------------- | ------------------------------ | | Claude Code | `claude` | | | Codex | `codex` | | | GitHub Copilot CLI | `copilot` | | | Cursor Agent CLI | `cursor` | | | OpenCode | `opencode` | also reports state | | Pi | `pi` | also reports state | | OMP | `omp` | state requires the integration | | Droid | `droid` | | | Devin CLI | `devin` | | | Kimi Code CLI | `kimi` | also reports state | | Kilo Code CLI | `kilo` | also reports state | | Hermes Agent | `hermes` | | | Qoder CLI | `qodercli` | | | Qwen Code | `qwen` | | | Letta Code | `letta` | CLI install only | | MastraCode | `mastracode` | state requires the integration | | Grok CLI | `grok` | | | Antigravity CLI | `antigravity-cli` | | | Amp | none | state only | | Kiro CLI | none | state only | | Maki | none | state only | | Gemini CLI | none | state only, less tested | | Cline | none | state only, less tested | ### Supported by the agent [Section titled “Supported by the agent”](#supported-by-the-agent) These agents report their own state to Herdr. There is nothing to install; run them in a Herdr pane. * [Command Code](https://commandcode.ai) * [Crush](https://github.com/charmbracelet/crush) * [Kiro CLI](https://kiro.dev/cli/) * [Muse Code](https://dev.meta.ai/products/muse-code) * [Prime Agent](https://github.com/PrimeIntellect-ai/prime-agent) An agent that also reports its resume command comes back in the same session after a Herdr server restart. If you build a coding agent, [Add Herdr support to your agent](/docs/add-herdr-support/) shows how to join this list. It takes a few calls to Herdr’s CLI or socket, and no change to Herdr. ## How status works [Section titled “How status works”](#how-status-works) For agents Herdr supports, Herdr finds the agent’s process in each pane and reads the live bottom of the pane, not the part you scrolled to. Rules in a detection manifest decide whether that screen means `idle`, `working`, or `blocked`. When an integration also reports state, Herdr uses those reports instead of reading the screen. For agents that support Herdr, the agent’s own reports decide the state. ## VMs and sandbox wrappers [Section titled “VMs and sandbox wrappers”](#vms-and-sandbox-wrappers) On Linux and macOS, a host-visible wrapper can hide the real agent process from Herdr. Set `HERDR_AGENT=` on the wrapper command to tell Herdr which existing agent screen manifest to use. For example, run `HERDR_AGENT=claude fence -- claude` on Linux or `HERDR_AGENT=claude nono run --profile claude-code -- claude` on macOS. The hint applies only to that foreground process. Herdr cannot see it if you set it only inside a VM or container. Avoid exporting it globally unless every inherited foreground process should be treated as that agent. Some restricted Linux runtimes do not expose a terminal foreground process group. Start the Herdr server with `HERDR_PROCESS_DETECTION=child-groups` to opt into direct child-process-group inference when native detection is unavailable. Native detection remains preferred, and the default `native` mode never performs this inference. The opt-in mode is best effort: a newer background job can be mistaken for the foreground job. The variable is read by the server and requires a restart; set it in the remote server environment rather than on an attaching client. ## Blocked state [Section titled “Blocked state”](#blocked-state) Blocked detection is deliberately strict for screen-manifest agents. Herdr only marks `blocked` when the live bottom-buffer snapshot matches known visible approval, question, or permission UI. If no manifest rule matches for a known agent other than Codex, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output. Codex falls back to `unknown` because its title and composer can look the same during an active turn and after a response. For those other agents, unusual new prompts may initially show as `idle` instead of `blocked` until Herdr learns that screen shape. The misclassification affects only the visible status and waits. It should not make Herdr send input or take destructive action. For Codex, a visible spinner or live activity timer can establish `working`, and a visible approval prompt can establish `blocked`. When Codex’s terminal title shows no spinner, Herdr reports `idle`. Codex stays `unknown` only when no rule matches, for example when Codex sets no terminal title, and waits for `idle` or completion may then time out. Managed startup uses the initial composer only to determine when it can accept a prompt; that observation does not change turn status. ## Detection manifests [Section titled “Detection manifests”](#detection-manifests) Bundled manifests live inside Herdr. Herdr also checks herdr.dev for remote manifest updates and applies valid per-agent rule updates automatically without requiring a Herdr restart. Remote manifests are stored in Herdr’s state directory. Set `[update] manifest_check = false` to disable background remote manifest checks. Local overrides can replace a remote or bundled manifest from the platform config directory: ```text ~/.config/herdr/agent-detection/.toml ``` Local overrides always win. Without a local override, Herdr uses the newer compatible manifest between the cached remote manifest and the bundled manifest in the running binary. On debug builds, the same config helper may use a development directory such as `herdr-dev`. Invalid override files are ignored with a warning and Herdr falls back to the cached remote or bundled manifest for that agent. Remote manifests patch detection rules for agents Herdr already knows how to identify. Adding a completely new agent still requires a Herdr binary update for process detection, labels, and integration behavior. The running server loads active manifests into memory on startup. Automatic remote manifest updates reload that in-memory cache after new rules are written. Run `herdr server update-agent-manifests` to fetch remote manifest updates immediately and reload the running server. After editing a local override manually, restart Herdr or run `herdr server reload-agent-manifests` to apply the file to the running server. Use `herdr agent explain` when a pane shows the wrong state: ```bash herdr agent explain herdr agent explain --file screen.txt --agent codex --json ``` Live explain is evaluated by the running server, so it reflects the active manifest cache. The explain output shows the agent, final state, whether screen detection was skipped by a full lifecycle authority, manifest source and version, cached remote version, local override shadowing, remote update status, matched rule, visible evidence flags, matcher and region evidence for evaluated rules, skipped-update reason for transcript viewers, and the idle fallback reason when no rule matched. Herdr can run inside tmux as the outer terminal environment. Agent detection does not inspect tmux sessions launched inside a Herdr pane. If a shell framework auto-enters tmux inside Herdr, Herdr sees `tmux` as the pane process instead of the agent behind it. If your shell automatically attaches to tmux whenever `TMUX` is unset, update its startup rule to exclude Herdr panes. Reattaching the outer tmux session from inside a Herdr pane can recursively shrink the terminal and make it flicker. Add the `HERDR_ENV` check to your existing condition before it runs tmux: ```zsh if [[ -z ${TMUX:-} && ${HERDR_ENV:-} != 1 ]]; then tmux new-session -A -s my-session fi ``` ## State rollups [Section titled “State rollups”](#state-rollups) The sidebar rolls state upward. A blocked agent makes its pane, tab, and workspace look blocked. A working agent makes the workspace look active. A done agent stays visible until you view it. This is the main Herdr workflow: start several agents, let them work in parallel, and use the sidebar to see which project needs a decision, which one is still running, and which one is ready to review. ## Custom agent labels [Section titled “Custom agent labels”](#custom-agent-labels) You can rename an agent target for display: ```bash herdr agent rename w1:p1 reviewer herdr agent rename reviewer --clear ``` Targets accept a unique live agent name or the pane ID that currently hosts the agent. Terminal IDs and bare agent-kind labels are not accepted. ## Custom status labels [Section titled “Custom status labels”](#custom-status-labels) Integrations report lifecycle state as semantic state only. Add display customization separately with pane metadata tokens. ```bash herdr pane report-agent w1:p1 \ --source custom:indexer \ --agent docs-bot \ --state working herdr pane report-metadata w1:p1 \ --source custom:indexer-display \ --token summary=indexing ``` `state` controls waits, notifications, and rollups. The `summary` token is display-only and can be used as `$summary` in an Agent sidebar row. Agent sidebar rows can also opt into `terminal_title` or `terminal_title_stripped`; neither appears in the default rows. The first shows the latest safety-normalized OSC 0/2 terminal title. The second removes one recognized leading activity or spinner glyph and following whitespace. Herdr owns these values on the server; they are ephemeral across a cold restart and remain independent of metadata titles and semantic agent state. Spinner animation can therefore update the raw title without producing a pane update when the stripped text stays the same. ## Attach directly to an agent [Section titled “Attach directly to an agent”](#attach-directly-to-an-agent) Attach your current terminal to one agent terminal instead of the full Herdr UI: ```bash herdr agent attach reviewer ``` Detach with `ctrl+b q`. Send a literal `ctrl+b` with `ctrl+b ctrl+b`. Scroll with the mouse wheel or plain page up/page down. Normal input jumps back to the bottom. Use `--takeover` if another direct attach client already owns input: ```bash herdr agent attach reviewer --takeover ``` Use `herdr terminal attach ` when you want the same direct attach behavior for a non-agent terminal. # CLI reference > Herdr commands for sessions, workspaces, tabs, panes, notifications, agents, waits, integrations, and status. Herdr’s CLI talks to the running server over the same local socket API used by integrations and agents. Most commands print JSON responses for deterministic automation in scripts. ## Launch and status [Section titled “Launch and status”](#launch-and-status) ```bash herdr # launch or attach to the default session herdr --remote workbox # attach through SSH, using local keybindings herdr --default-config # print default config herdr update # download and install from the configured channel herdr completion zsh # generate a zsh completion script herdr channel show # print stable or preview herdr channel set preview # opt into preview builds herdr channel set stable # return a direct install to stable herdr --version # print version ``` Optional launch and update settings: * Add `--session ` to use a named session instead of the default. * Add `--remote-keybindings server` to remote attach to use server keybindings instead of local ones. * Experimental live handoff requires explicit `--handoff` on `herdr --remote` or `herdr update`. It is not the normal setup or connection path; see [Updates](/docs/install/#update). Status commands: ```bash herdr status herdr status server herdr status client ``` API schema commands: ```bash herdr api schema herdr api schema --json herdr api schema --output herdr-api.schema.json ``` `herdr api schema` prints a short summary of the socket protocol schema bundled with the installed binary. Use `--json` for the full JSON Schema document, or `--output PATH` to write that document to a file. ## Saved SSH machines [Section titled “Saved SSH machines”](#saved-ssh-machines) ```bash herdr machine list herdr machine add workbox herdr machine add workbox --label "Build machine" herdr machine rename --label "New name" herdr machine disable herdr machine enable herdr machine remove ``` In an interactive terminal, `machine add` discovers running sessions and lets you choose when several are running. No running sessions, or no Herdr installation, uses `default`; failed queries against an installed binary require an explicit choice. Add `--remote-session ` to skip discovery. Non-interactive commands use `default` unless that flag is supplied. `machine list` accepts optional `--json` for scripts. See [Connecting machines](/docs/connecting-machines/) for the full setup and connection guide. `machine add` checks the remote installation’s capabilities, installs or updates with approval only when needed, and starts the requested session’s background server before saving. Compatible release versions do not need to match. Run setup in an interactive terminal when installation or restart approval is required; failed or cancelled setup does not save a profile. Replacing a running server requires explicit approval with a default answer of No, and stops its pane processes. `machine add` never enables experimental handoff implicitly. Changes apply automatically to open local Herdr clients, normally within a second. Added or enabled machines connect in the background; renaming does not reconnect. Removing or disabling disconnects only that machine and leaves its remote sessions running. Removing the machine you are viewing returns to Local, or shows Local as unavailable until it reconnects. Each profile stores an opaque ID, label, SSH target, explicit remote session, and enabled state in client state. Herdr does not store passwords, private keys, or other SSH credentials. Use `herdr machine status [] [--json]` for fresh, noninteractive SSH and remote Herdr checks. `reachable` describes this check, not a TUI’s current connection. Use `herdr machine reconnect ` in a terminal for SSH authentication and verification; it does not install or update Herdr. Open clients retry failed connections within 30 seconds. Clicking `! auth` or `! error` shows the latest error and CLI guidance; collapsed sidebars show `!`. See [Recovering SSH authentication](/docs/connecting-machines/#recovering-ssh-authentication) for platform limits. For remote setup, use `herdr --remote workbox`, adding `--session ` only for a named session. Workspace, tab, pane IDs, and agent names belong to a single server. Selecting a machine in the UI does not retarget CLI commands. Use the global **prefix** `--machine ` to route API commands to a saved SSH machine: ```bash herdr --machine "Build machine" agent list herdr --machine pane list herdr --machine "Build machine" agent prompt w1:p1 "review this change" herdr --machine "Build machine" worktree create --cwd /srv/project --branch review ``` The selector must match an enabled saved profile ID or a unique, case-sensitive label, not an arbitrary SSH hostname. The saved remote session is used; combining `--machine` with `--session` or `--remote` is an error. Without the prefix, commands retain their existing local session/socket behavior. Supported commands are `workspace`, `worktree`, `tab`, `pane`, `notification`, `agent` (except `attach` and local `explain --file`), `api snapshot`, `status server`, and API-backed plugin commands (`link`, `unlink`, `enable`, `disable`, `list`, `action`, `log`, `pane`). Server commands support `stop`, `reload-config`, `agent-manifests`, and `reload-agent-manifests`. Local installation/configuration commands, plugin installation, session management, and interactive terminal attachment are not forwarded. Requests and responses travel through the JSON API over non-interactive SSH; API payloads are not interpolated into the SSH shell command. No open TUI is required, and the bridge never installs, starts, or restarts a server. Update the local CLI and remote Herdr installation to support machine forwarding, and keep the running remote server’s API protocol compatible. Authentication, unavailable machines, and incompatible versions fail without falling back to Local. Requests are not automatically retried after connection failure. Local pane IDs are not inherited by remote commands. Use explicit remote IDs; `--current` cannot refer to the caller’s local pane. Remote worktree paths must be absolute, `~`, or start with `~/` (expanded on the server); plugin link paths must be absolute. The prefix targets one machine at a time; combined listings and routing through another TUI’s connections are not included. ## Shell completions [Section titled “Shell completions”](#shell-completions) ```bash herdr completion zsh herdr completions zsh herdr completion bash herdr completion fish herdr completion powershell herdr completion elvish ``` `completion` prints the script to stdout. `completions` is an alias. For a temporary zsh session, load the script directly: ```bash source <(herdr completion zsh) ``` For a persistent zsh setup, write the generated `_herdr` function somewhere on your `fpath` before `compinit` runs: ```bash mkdir -p ~/.zfunc herdr completion zsh > ~/.zfunc/_herdr ``` Then make sure your `.zshrc` contains: ```zsh fpath=(~/.zfunc $fpath) autoload -Uz compinit compinit ``` ## Server [Section titled “Server”](#server) ```bash herdr server herdr server stop herdr server reload-config herdr server agent-manifests [--json] herdr server update-agent-manifests [--json] herdr server reload-agent-manifests ``` `herdr server` runs the headless server explicitly. Use it for supervised or service-style setups. `reload-config` applies reloadable settings without restarting panes. `agent-manifests` shows the active agent detection manifest sources, cached remote versions, and last remote update results. `update-agent-manifests` fetches remote manifest updates immediately, reloads them into the running server, and prints the updated manifest status; pass `--json` for the raw status response. `reload-agent-manifests` reloads agent detection manifests into the running server after local override edits. ## Notifications [Section titled “Notifications”](#notifications) ```bash herdr notification show