herdr: a persistent terminal server for coding agents

The problem herdr targets: agents that block while you are looking elsewhere

Running one coding agent in one terminal is easy. Running five is not, because the failure mode is not a crash. It is an agent that has stopped and is waiting for a confirmation, a diff review or a clarifying answer, in a pane you are not watching. The README frames this directly: every pane is marked working, blocked, or idle, and when an agent stops and needs an answer, herdr says so. That status model is the product. The rest of the tool exists to make those panes survive. herdr is a background server, and the terminals live inside it. The README claims that closing the lid, dropping the network or restarting the machine leaves agents working and brings sessions back, and that you reattach from any terminal or over ssh. The audience is people who already run claude code, codex, cursor, opencode or grok and want to keep them running without a tmux config they maintain by hand. herdr does not wrap or replace those agents; per the README it owns their terminals.

Server, panes and a socket: how herdr is put together

The architecture follows from a background server owning pseudo-terminals. The Cargo manifest lists portable-pty pinned to exactly 0.9.0 and patched to a vendored copy under vendor/portable-pty, plus tokio for the async runtime, ratatui and crossterm for rendering, and interprocess for the socket layer. That dependency set matches the description: a Rust TUI client talking to a long-lived process that holds PTYs. Because the server owns the PTYs rather than your terminal emulator, detaching is not a special mode. The README says ctrl+b q detaches and running herdr again reattaches. The second half of the design is the API. The repository ships docs/next/api/herdr-api.schema.json, and the README describes a pure socket API through which agents spawn panes, prompt each other, and wait until another agent is genuinely blocked. That last capability is the interesting one: an orchestrating agent can block on a real state transition rather than polling output text and guessing. The install manifest also includes skills/herdr/SKILL.md, which the README links as the agent skill, so the instructions an agent needs to drive herdr travel with the binary.

Installing herdr and getting a first agent pane running

The README gives a one-line installer for Unix-like systems. It pipes install.sh from herdr.dev into sh, which means you are trusting a remote script; read it first if that matters to you.

curl -fsSL https://herdr.dev/install.sh | sh

Alternatives listed in the README are Homebrew, mise, and a PowerShell installer for Windows. Windows users on endpoint-protected machines are pointed at a separate page, herdr.dev/docs/windows-beta, so the Windows path is documented as beta.

brew install herdr

mise use -g herdr

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

Prebuilt binaries are also published on the GitHub releases page. Once installed, you start the server by running herdr with no arguments in the directory where the work lives, then start your agent inside a pane as you normally would. The README's own summary of the loop is: run your agents, split panes, walk away.

herdr

Detaching is ctrl+b q, and running herdr again reattaches. If you want the full walkthrough, herdr.dev/docs/quick-start is the page the README links to. Building from source is also documented, and it is a normal Cargo project with a justfile on top.

git clone https://github.com/herdrdev/herdr
cd herdr
cargo build --release

Where herdr gets in the way

The honest limitation is that herdr inserts itself between you and your terminal, and that is a real cost. Your scrollback, your terminal's own search, your shell integration and any emulator-specific feature now sit on top of a client that renders through ratatui and crossterm. If you have tuned your current setup around those features, herdr will not reproduce them, and the README does not claim it will. The second constraint is the persistence promise. The README says sessions come back after a machine restart, but a restarted server is a restarted process: what exactly is restored, and what is lost, is the kind of question that belongs in the session-state documentation rather than the README, and the README does not answer it. Treat the persistence claim as something to verify against herdr.dev/docs/session-state before you rely on it for long-running work. Third, the agent-native behaviour is only as good as the status detection. herdr decides a pane is blocked based on how the agent behaves, and the repository contains scripts for checking an agent-detection manifest, which suggests that detection is maintained per agent rather than inferred generically. An agent herdr does not recognise will not produce useful status. Fourth, this is a young project. The last push was on 2026-08-19, and the release list shows v0.8.2 alongside dated preview builds, which is the shape of software that is still moving. The Cargo manifest is at 0.9.0. Expect churn in the socket API and the configuration format.

herdr compared with tmux and zellij

The comparison people reach for is tmux, and the difference is not the keybindings. tmux is a general multiplexer: panes, windows, sessions, and a scripting interface that can send keys and capture output. You can absolutely run agents under tmux, and many people do. What tmux does not give you is a semantic state for each pane. It cannot tell you that the thing in pane three is blocked on a question, because it does not know what is running there. herdr's pane states and its socket API are built for exactly that, and the README positions the API as something agents use, not just something you script against. zellij occupies a similar place to tmux with a different layout and plugin model. The distinguishing question for both is whether you want a general-purpose multiplexer that you configure, or a server that already understands the agents inside it. If your answer is the former, tmux or zellij is the smaller dependency and the more predictable one. If your answer is the latter, the status model is the reason to switch. herdr also overlaps with terminal emulators that have their own split and session features, but those live in the emulator, so detaching and reattaching from a different machine over ssh is not the same proposition.

Licence, maintenance and the cost of upgrading

herdr is Apache-2.0, both in the README and in the Cargo manifest's license field. That is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your own code. It does require that you keep the licence and notice files when you redistribute the binary, and the usual caveat applies: this is a description of the licence text, not legal advice, and if you are embedding herdr in a product you should have someone read the actual LICENSE file. On maintenance, the facts are narrow. The repository is not archived, and the last push was on 2026-08-19. Beyond that, the README does not state a support policy, a release cadence or a deprecation window, and the release list mixes tagged versions with dated preview builds, so preview artifacts are clearly a separate channel from stable releases. The practical upgrade cost is configuration drift. The tool reads a config file, and it ships a JSON schema for its API, which is the kind of artefact that changes shape between minor versions in a project this young. Pin a version for anything you depend on, and read CHANGELOG.md before moving.

Editorial conclusion

Adopt herdr if you run several coding agents at once and lose track of which one is waiting for input, or if you want agents to spawn and coordinate panes themselves. Skip it if you only need a plain shell multiplexer, or if you depend on a terminal feature that only your current emulator provides. Before committing, verify the three things the README leaves open: which agents are listed as supported at herdr.dev/docs/agents, what the session-state documentation says about where state is persisted, and whether your terminal handles the mouse and prefix-key mix the way you expect.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes