I killed the herdr server with kill -9 while two panes were running, then restarted it and checked what came back. The layout returned perfectly — two panes, one tab, correct working directories. The agent state did not: my registered agent record went from one to zero. And every terminal ID had changed — term_656ea96f21af61 became term_656ea9edb17891. Same furniture, new processes underneath.
That single test tells you more about the herdr terminal multiplexer than any feature list, and it is the test almost nobody publishing about this tool has actually run. Most of what I had read before installing it was a rewritten README with a first-person costume on. So here is what I did, what my terminal actually printed, and where I think herdr earns a place in a multi-agent workflow versus where the excitement runs ahead of the software.
One search-saving note first: the tool is herdr — no "e" before the "r". It lives at ogulcancelik/herdr on GitHub and has since grown into Herdr, Inc., a Y Combinator-backed company.
What herdr is
herdr is a terminal multiplexer that tracks the semantic state of AI coding agents running inside its panes. Where tmux persists terminals, herdr persists terminals and knows whether the agent in each pane is idle, working, or blocked waiting on your approval. It ships as a single Rust binary, runs a background server so sessions survive detaching, and exposes a local socket API that lets agents create panes, read each other's output, and wait on each other's state.
I ran my tests against version 0.7.4 in July 2026, driving everything headlessly through the CLI and socket API rather than the interactive TUI — so when I describe the sidebar, I am reporting the docs, and everything else is output I captured myself. The project moves fast: as I update this, the site lists v0.8.0 and an Apache 2.0 license, which differs from the licensing I recorded at test time. Pre-1.0 software with a versioned protocol (mine reported protocol 16) means you should treat any specific number here, including these, as a snapshot.
brew install herdr
herdr server &
herdr status
# server: running, version 0.7.4, protocol 16
# socket: /Users/mejba/.config/herdr/herdr.sock
Small correction to a number I kept seeing repeated: write-ups called it a "~10MB binary." On my machine, ls -lh said 16M. Small either way — but if you are going to publish a number, measure it.
Which agents it actually understands
This is where the tool justifies itself or does not, so I went to the binary instead of a blog post. herdr integration list returns fourteen agents with full lifecycle-hook integrations:
pi, omp, claude, codex, copilot, devin, droid, kimi,
opencode, kilo, hermes, qodercli, cursor, mastracode
Everything else falls back to screen-manifest detection: herdr snapshots the live bottom of the pane buffer and evaluates TOML pattern manifests against it. The two-tier design is worth understanding before you commit. Hook integration is authoritative — the agent tells herdr its state. Screen detection is inference — herdr guesses from rendered text, which breaks whenever the agent's UI changes. If your stack is in the first list (Claude Code and Codex both are), state tracking is reliable. If not, you are betting on pattern matching.
Blocked detection is deliberately conservative: herdr only flags blocked when the screen matches a known approval pattern, so it under-reports rather than cries wolf. Right call.
What the Claude Code integration does to your machine
Run herdr integration install claude and read the output carefully:
installed claude integration hook to /Users/mejba/.claude/hooks/herdr-agent-state.sh
ensured claude settings at /Users/mejba/.claude/settings.json
It edits your Claude Code settings file, registering a hook with a wildcard "matcher": "*". Before trusting that, I opened the installed script — and came away impressed. The first thing it does is bail out unless it is actually inside a herdr pane:
[ "${HERDR_ENV:-}" = "1" ] || exit 0
[ -n "${HERDR_SOCKET_PATH:-}" ] || exit 0
[ -n "${HERDR_PANE_ID:-}" ] || exit 0
command -v python3 >/dev/null 2>&1 || exit 0
Outside herdr, the environment variables do not exist, so the hook is a free no-op. That is exactly the right design for something injecting itself into your primary coding tool's config. Two caveats from the file itself: it is managed by herdr and gets overwritten on update (add sibling hooks, do not edit it), and it silently requires python3 on your PATH. herdr integration status audits what is installed, and uninstalling is one command per agent — verify your settings file afterward rather than assuming.
The socket API is the real product
The multiplexing is table stakes. The part that made me pay attention is a Unix socket at ~/.config/herdr/herdr.sock speaking newline-delimited JSON, with CLI wrappers over workspaces, tabs, panes, agents, worktrees, and layouts. Pane addressing is workspace:pane — readable and scriptable:
herdr workspace create --cwd /tmp/herdr-test --label api-test
herdr pane split w1:p1 --direction right
herdr pane run w1:p2 "echo HERDR_REAL_TEST; sleep 4; echo FINISHED"
herdr pane read w1:p2 --source recent --lines 20
pane read takes four --source modes: visible, recent (wrap-aware scrollback), recent-unwrapped (for grepping logs), and detection — the exact snapshot herdr's agent detection is evaluating. That last one is a genuinely thoughtful affordance: when detection misfires, you can see precisely what herdr saw.
And then there is the primitive that separates this from a nicer tmux: a blocking wait on another pane's agent state. I tested it directly — flipped a pane to working, spawned a background job to flip it back to idle after five seconds, and blocked on it:
herdr pane report-agent w1:p2 --source custom:test --agent build-bot --state working
( sleep 5; herdr pane report-agent w1:p2 --source custom:test --agent build-bot --state idle ) &
herdr wait agent-status w1:p2 --status idle
The wait returned after exactly five seconds with the triggering event as JSON. Sit with what that enables: a shell script where Claude Code implements, and the moment it goes idle, Codex starts the review — no polling loop, no arbitrary sleep 300, no human watching a terminal. The --source custom: flag means any process can report state, so your build script can register as an agent and join the orchestration graph alongside the fourteen blessed ones.
This is the missing piece of the setup I described in running parallel Claude Code agents with git worktrees: worktrees give you isolation for free, but sequencing agents has always meant babysitting or brittle polling. herdr even ships worktree helpers (herdr worktree create --workspace-id w1 --branch worktree/api), which suggests the author hit the same wall I did.
The crash test, in full
The persistence claim is herdr's headline, so I tested the ungraceful path. Before the crash, herdr api snapshot showed two panes, one tab, one registered agent. After kill -9 and a restart:
panes after restart: 2 tabs: 1 agents: 0
w1:p1 term: term_656ea9edb17891 cwd: /private/tmp/herdr-test
w1:p2 term: term_656ea9edb20c52 cwd: /private/tmp/herdr-test
Three distinct outcomes, and the distinction is the whole story. The layout survived — panes, tabs, directories, structure, even through SIGKILL. The processes did not — every terminal ID changed; those are fresh shells in the right directories, and a dev server or test run would have died with the old ones. The agent state did not — registrations are in-memory and die with the server.
So the accurate mental model: detaching is lossless, crashing is not. Detach with ctrl+b q and the server keeps every process alive — that is the strong path you will use daily. When the server itself dies, you get your furniture back but not your running work. Two mitigations exist: native agent session restore is on by default (it resumes supported agents' conversations via session references the hooks reported — which makes installing those hooks matter more than it first appears), and pane screen-history replay is off by default because scrollback can contain secrets and tokens. Both defaults are correct.
Versus tmux and zellij, honestly
The project's own framing is unusually honest: tmux persists terminals; herdr persists agent workspaces and understands agent state. Strip the positioning and the delta is narrow but sharp — all three keep persistent PTY sessions and reattach over SSH; only herdr does semantic agent state, agent attachment, and an agent-shaped API with read, send, wait, and split as first-class operations.
Choose tmux for production servers, tuned configs, and boring reliability. Choose zellij for discoverability and its WebAssembly plugin system. Choose herdr if you regularly run three or more coding agents at once and lose time to the question which one is waiting on me right now? If you are not running multiple agents concurrently, herdr is a worse tmux with fewer plugins — the agent-state feature is the entire value proposition.
What herdr gets wrong
No sandboxing. herdr is a multiplexer, not a security boundary. Every agent in every pane has your full filesystem access, and handing autonomous agents a socket API that spawns panes builds a convenience layer, not a containment layer. Isolate separately — containers or worktrees.
Windows is beta and asymmetric. The ConPTY backend does not support --remote, so SSH remote attach is Mac/Linux only for now.
It is young. Pre-1.0, explicitly versioned protocol, docs that tell you to expect breaking changes. If you build serious automation on this API, budget for maintenance — and since the licensing terms I recorded at test time differ from what the site lists today, read the LICENSE file yourself before this goes near a commercial product.
My recommendation
I am not ripping out my setup, but herdr stays installed. My multi-agent pain was never starting agents — it is the dead minutes where an agent finished and I did not notice, or sat blocked on an approval prompt in a pane I was not watching. Anthropic solved this inside their own tool with the Agents View dashboard; herdr solves it across every tool, which matches how I actually work — Claude Code and Codex in the same repo most days. It attacks the same mess CMUX attacks from the GUI side, but stays in the terminal and adds semantics instead of chrome.
Install it, run one real project through it for a week, and notice whether the state sidebar changes your behavior. If you check it instead of cycling panes, it has earned its place. If you forget it exists, you are not running enough agents for it to matter yet — a fine answer. And before you trust it with anything real, run my test: kill the server and see what comes back. Any tool that holds your work in memory deserves to be asked what happens when it dies.
Multi-agent orchestration setups like this — worktrees, state-aware sequencing, the whole pipeline — are a recurring part of my client work; the projects page shows what those builds look like in practice.
