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/) # 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`, `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. For Codex on Windows, the delay grows with 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. 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.0/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.0/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.0/skills/herdr/SKILL.md) # Agents > See what Herdr can detect, how agent state works, and how integrations improve it. 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) Automatic detection works out of the box for common coding agents. The table shows which signal determines `idle`, `working`, and `blocked` for each one. | Agent | State authority | Integration role | | ------------------ | ---------------------------------------------------------- | ----------------- | | Pi | lifecycle hooks when installed; otherwise screen manifest | state and session | | OMP | lifecycle hooks when installed | state and session | | GitHub Copilot CLI | screen manifest | session | | Devin CLI | screen manifest | session | | Kimi Code CLI | lifecycle hooks when installed; otherwise screen manifest | state and session | | Hermes Agent | screen manifest | session | | Qoder CLI | screen manifest | session | | Qwen Code | screen manifest | session | | Droid | screen manifest | session | | OpenCode | lifecycle plugin when installed; otherwise screen manifest | state and session | | Kilo Code CLI | lifecycle plugin when installed; otherwise screen manifest | state and session | | MastraCode | lifecycle hooks when installed | state and session | | Claude Code | screen manifest | session | | Codex | screen manifest | session | | Cursor Agent CLI | screen manifest | session | | Amp | screen manifest | none | | Grok CLI | screen manifest | session | | Antigravity CLI | screen manifest | session | | Kiro CLI | screen manifest | none | | Maki | screen manifest | none | | Muse | screen manifest | none | Detected but less thoroughly tested: Gemini CLI and Cline. Unsupported agents still run normally as terminal processes. They just may not get rich state unless you add an integration or report state over the socket API. ## Status authority [Section titled “Status authority”](#status-authority) Herdr first detects the foreground process in each pane. After that, each pane has one status authority. For agents with complete lifecycle hooks, the integration is authoritative when it is installed and actively reporting for the running pane. Herdr uses those hook reports for `idle`, `working`, `blocked`, and session identity. It does not also run screen manifest fallback for that same lifecycle authority. This avoids two competing sources of truth. For agents without complete lifecycle hooks, Herdr identifies the foreground process and reads the live bottom-buffer screen snapshot. It evaluates TOML manifests against that snapshot to classify `idle`, `working`, and `blocked`. For agents that emit them, manifests can also match terminal title and progress (OSC) sequences as detection evidence; when that evidence is absent, screen rules carry detection on their own. The screen snapshot comes from the recent bottom of the pane buffer, not the scrolled viewport. If you scroll back in Herdr, detection still follows the live agent UI at the bottom. Integrations marked `session` in the table above are intentionally not lifecycle authorities. They provide native session identity for restore, but their hooks do not cover the whole lifecycle. They can miss permission approval results, escape interrupts, or other transitions. For those agents, Herdr still uses screen manifest detection. ## 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, Herdr falls back to `idle` and labels that fallback as `default_known_agent_idle_fallback` in explain output. This means unusual new agent 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. ## 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. ## 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. ## Direct integrations [Section titled “Direct integrations”](#direct-integrations) Install the integration for each agent you use to give Herdr hook or plugin reports instead of screen detection alone: ```bash herdr integration install claude herdr integration status ``` Each supported agent has its own integration name and behavior. See [Integrations](/docs/integrations/) for the per-agent details and the full install list. If you are building an agent, the [custom integration guide](/docs/integrations/#integrate-your-own-agent) shows how to report lifecycle state without adding native support to Herdr. ## 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 --label "Build machine" herdr machine rename --label "New name" herdr machine disable herdr machine enable herdr machine remove ``` By default, `machine add` uses the remote default session. Add `--remote-session ` only for a named session. `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. Automatic connections and reconnects are non-interactive. If a host key, password, key passphrase, MFA step, install, update, or restart needs approval, the machine shows Attention instead of opening a hidden prompt. Run the standalone command printed by Herdr, such as `herdr --remote workbox`, to complete that setup in the foreground, then restart the client. Include `--session ` only when the profile targets a named session. Workspace, tab, pane IDs, and agent names belong to a single server. Selecting a machine in the UI does not change the session or socket inherited by commands running in an existing pane. For remote automation, run the CLI on the intended host against the intended session and discover its IDs there. ## 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