herdr: The Always-On Terminal Runtime for Coding Agents

What it is

herdr is a terminal runtime built for coding agents: a single Rust binary with no Electron, running as a background server inside whatever terminal you already use, holding the terminal processes of Claude Code, Codex, Cursor, OpenCode, Grok and the rest. It does not wrap or replace any agent; it owns their terminals. The project's own line is "the runtime your coding agents live on": close the lid, drop the network, restart the machine, and agents keep working; reattach from any terminal or over ssh and the session is where you left it.

The project is Apache-2.0 licensed, past thirty-five thousand GitHub stars, and release 0.8.2 in August 2026 made Windows support generally available. Installation is a curl script, Homebrew or mise; afterwards you start it where the work lives by running herdr in that directory.

Server and client: terminals live in the server

By default herdr is a background server plus one or more attached clients. The server owns panes and process state; the client is only the terminal UI attached to it. The hierarchy has three levels: a workspace is the top-level project container, one per repo, task or investigation; a tab is a layout inside a workspace, separating views such as agents, logs, server or review; a pane is a real terminal, since herdr renders its output, sends input back to the process, and preserves the pane across client detach.

Interaction is mouse-native: clicking panes, tabs, workspaces and agents, dragging split borders, selecting text and right-click menus are all first-class, while tmux-style prefix keys remain a parallel layer, with ctrl+b q to detach and herdr to reattach. Keyboard and mouse are chosen per moment, not per tool. Named sessions are fully separate runtime namespaces with their own panes, sockets and persisted state, though the docs recommend workspaces first.

Four persistence paths

The documentation states four state paths plainly. Detach and reattach is the strongest: original processes never stop, so panes, shells, agents, tests and servers keep running inside the server. A server restart loses processes but restores the session shape from a snapshot: workspaces, tabs, panes, working directories, layout and focus return, and panes with no stronger path come back as new shells in their saved directories.

Pane screen history replay is opt-in and experimental: it restores recent terminal contents after a full restart without restoring the old process. It is off by default because pane output can contain secrets, tokens, prompts and command results; once enabled, history lives in session-history.json beside session.json, and the docs say to treat that directory like terminal history. Native agent session restore is on by default: herdr uses session references reported by official integrations to restart supported agent panes after a server restart, resuming only panes that reported a native session reference. Updates get a separate --handoff path: best-effort live handoff for supported running servers, keeping processes alive and screens live when it succeeds.

Evidence-based agent state detection

herdr's signature feature is that every pane carries a state: blocked means the agent needs input, approval or a decision; working means actively running; done means finished but not yet looked at; idle means finished or waiting and already seen; unknown means herdr cannot confidently classify it. Sidebar state rolls up from the agents inside a workspace, so one glance shows which project needs attention, and you never hunt for the stuck one.

Detection is evidence-based and decoupled from the terminal parser: the detector reads a screen snapshot and never touches parser or viewport state, and it explicitly refuses the user-visible viewport as a status source because users can scroll it. Each agent has a manifest, twenty-one toml files under src/detect/manifests covering claude, codex, cursor, gemini, github-copilot, grok, opencode, qwen, cline, devin, droid, amp, antigravity, hermes, kilo, kimi, kiro, maki, muse, pi and qodercli, encoding which visible controls are invariant and which are alternatives as explicit AND/OR gates; matching whole-pane incidental text is forbidden. Changing a manifest requires capturing bottom-buffer evidence first with herdr agent read --source detection, and the repo ships capture and check scripts so detection rules stay testable artifacts rather than hand-tuned regexes.

A control surface written for agents

herdr treats agents as first-class users. The CLI and the local socket API share one control surface: create, list, focus, rename and close workspaces and tabs; split, swap, resize, read and send input to panes; list, read, prompt and wait on agents; report custom state from hooks and plugins; subscribe to events and wait for output or state changes. herdr api schema prints the JSON Schema bundled with the binary, covering raw requests, success and error responses, emitted events and subscription events.

Two details show the surface is genuinely agent-shaped: agent prompt refuses to send text or Enter to an agent already waiting at an approval or question dialog and returns agent_blocked instead; agent start waits for new pane shells and first-run prompts to become ready rather than racing them. The repository ships an agent skill (skills/herdr/SKILL.md) whose first step verifies HERDR_ENV=1, so an agent outside herdr must not inspect or control the focused session, and which makes the installed binary's help output the authority for syntax, forbidding argument-less probes of mutating commands. Agents can therefore spawn panes, prompt each other, and wait until another agent is genuinely blocked.

Terminal engine and performance architecture

Terminal emulation runs on a vendored Ghostty VT engine (libghostty-vt) plus portable-pty, with a separate kitty graphics protocol module; the Windows path uses ConPTY and became generally available in 0.8.2, and Windows clients can attach with --remote to Linux and macOS servers. A headless server with no attached client uses a configurable 120x40 virtual terminal instead of 80x24.

AGENTS.md turns performance into architectural law. AppState is pure data, testable without PTYs or async, kept separate from PaneRuntime; compute_view handles geometry and mutations while render only draws and never mutates; platform behavior lives in per-OS files under src/platform so core modules carry no target-OS conditionals. Work reachable from view computation, rendering, background-pane resizing, PTY parsing, detection and client frame fanout is treated as a multiplicative path, priced per byte, event or render times panes, tabs and attached clients; pane-scaled loops may not collect aggregate state, touch the filesystem or allocate when a scalar fact suffices, and hidden panes keep parsing output without triggering presentation work. The changelog records the matching fix: busy multi-pane sessions avoid redundant hidden-pane wakeups and full terminal-state formatting, preventing CPU regressions from high-rate background output.

Ecosystem and release posture

The plugin marketplace runs as its own worker: it discovers valid manifests at repository roots and subdirectories, groups multiple plugins under each repository, and publishes their versions and exact default-branch commits, while the plugin registry lives in the persistence layer beside session snapshots. Official integrations carry two jobs: reporting session references for native restore, and letting hooks and plugins report custom agent state.

Release engineering is equally heavy: the repo keeps vendor verification, docs translation parity, config reference checks, agent detection manifest checks, Windows ConPTY packaging and a battery of smoke and performance scripts. Documentation ships in English, Japanese and Chinese, with a Simplified Chinese README. For people running several coding agents in parallel, herdr's answer is not another agent wrapper but a terminal that is itself a runtime: stateful, evidence-driven, and controllable by the agents living inside it.