herdr Terminal Multiplexer: I Crash-Tested It

herdr Terminal Multiplexer: I Crash-Tested It

I killed the server with kill -9 while two panes were running. Then I restarted it and checked what came back.

The layout came back perfectly — two panes, one tab, both sitting in the right working directory. 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 shape, new processes underneath.

That single test tells you more about the herdr terminal multiplexer than any feature list will, and it's the test almost nobody publishing about this tool has actually run. So let me walk through what I did, what the numbers were, and where I think this thing genuinely earns a place in a multi-agent workflow versus where the marketing is running ahead of the software.

First, a correction that will save you a fruitless search. The tool is called herdr — no "e" before the "r". I went looking for "Herder" and found nothing. It's ogulcancelik/herdr on GitHub, built by Turkish developer Oğuz Çelik, and it hit #1 on GitHub Trending on June 30, 2026.

What is the herdr terminal multiplexer?

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 output, and wait on each other. Version 0.7.4 landed July 15, 2026, under a dual AGPL-3.0-or-later and commercial license.

That's the honest one-paragraph version. Now the part where I stop quoting the docs.

How I actually tested it (and what I couldn't test)

I want to be precise about my methodology, because a lot of what's been written about this tool is a rewritten README with a first-person costume on top.

I installed herdr through Homebrew on an arm64 Mac:

brew install herdr
herdr --version
# herdr 0.7.4

Then I ran the server headless and drove everything through the CLI and socket API:

herdr server &
herdr status

client:
  version: 0.7.4
  channel: stable
  protocol: 16

server:
  status: running
  version: 0.7.4
  protocol: 16
  compatible: yes
  socket: /Users/mejba/.config/herdr/herdr.sock

Here's my limitation, stated up front: I drove herdr headlessly, not through its interactive TUI. I did not click panes with a mouse or drag borders around. So when I talk about the sidebar or the mouse-first interface, I'm reporting what the docs describe, not what I personally exercised. Everything else in this post is command output I captured on July 19, 2026.

That distinction matters because the headless path is where the interesting claims live anyway. The sidebar is a UI. The socket API is the actual product.

One number worth correcting while I'm here: several write-ups describe herdr as a "~10MB" binary. On my machine it's 16MB:

ls -lh /opt/homebrew/opt/herdr/bin/herdr
# 16M

Small either way. But if you're going to publish a number, measure it.

Is anyone actually using this, or is it just GitHub stars?

Stars are a vanity metric. Installs are not, and Homebrew publishes them.

As of my test, brew info herdr reported 13,372 installs in the last 30 days and 16,826 over 90 days. That 30-day figure being roughly 80% of the 90-day figure tells you the adoption curve is steep and recent, not a long tail from an old release. It also reported 7 build errors in 30 days, which is a low failure rate.

For a project a few months old, that's real traction — and it's a far more defensible signal than the star count, which I've seen quoted as 12.2k, 15k, 17.7k, and 18k across four different articles published within weeks of each other.

The agent detection question: which agents actually work?

This is where the tool either justifies itself or doesn't, so I went to the source rather than a blog post. Running herdr integration list gives the authoritative set of agents with full lifecycle hook integrations — fourteen of them:

pi, omp, claude, codex, copilot, devin, droid, kimi,
opencode, kilo, hermes, qodercli, cursor, mastracode

Beyond those fourteen, herdr falls back to screen-manifest detection — it reads a snapshot of the live bottom of the pane buffer and evaluates TOML pattern manifests against it. That covers agents like Grok CLI, Antigravity CLI, Kiro CLI, and Maki. Gemini CLI and Cline are documented as less thoroughly tested.

The two-tier design is the smart part, and it's worth understanding before you decide whether herdr will work for your stack. Hook-based integration is authoritative — the agent tells herdr what it's doing. Screen detection is inference — herdr guesses from pixels. If your agent is in the first list, state tracking is reliable. If it's in the second, you're depending on pattern matching against a UI that can change with any release.

The documented states are idle, working, and blocked, with unknown as the starting value before detection kicks in. Blocked detection is deliberately conservative — herdr only flags blocked when the screen matches a known approval or question pattern, which means it will under-report rather than cry wolf. Good call.

What installing the Claude Code integration does to your machine

I ran this, and I think everyone should know exactly what it does before they do:

herdr integration install claude

installed claude integration hook to /Users/mejba/.claude/hooks/herdr-agent-state.sh
ensured claude settings at /Users/mejba/.claude/settings.json

Read that second line again. It edits your Claude Code settings file. Specifically, it registers a hook with a wildcard matcher:

{
  "hooks": [
    {
      "command": "bash '/Users/mejba/.claude/hooks/herdr-agent-state.sh' session",
      "timeout": 10,
      "type": "command"
    }
  ],
  "matcher": "*"
}

I opened the installed script before trusting it, and I came away impressed. The guard clauses are the first thing that runs:

[ "${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 a herdr pane, those environment variables don't exist, so the hook exits immediately and costs you nothing. It's a no-op when herdr isn't running. That's exactly the right design for something that injects itself into your primary coding tool's config.

Two caveats the file states about itself, which I'd take seriously. The header says it's managed by herdr and that reinstalling or updating overwrites it — so don't edit it, add sibling hooks instead. And it depends on python3 being on your PATH, which is a silent-failure mode on a stripped-down machine.

herdr integration status gives you a clean audit of what's installed:

claude: current (v7) (/Users/mejba/.claude/hooks/herdr-agent-state.sh)
codex: not installed (/Users/mejba/.codex/herdr-agent-state.sh)
...

Uninstalling is a single command per agent, and I'd verify the settings file afterward rather than assume.

The socket API is the real product

Everything above is table stakes. This is the part that made me actually pay attention.

herdr exposes a Unix domain socket at ~/.config/herdr/herdr.sock speaking newline-delimited JSON. Protocol version 16 on my install. You can talk to it raw, or through CLI wrappers that cover workspaces, tabs, panes, agents, worktrees, notifications, and layouts.

I created a workspace and split a pane:

herdr workspace create --cwd /tmp/herdr-test --label api-test
herdr pane split w1:p1 --direction right

The response comes back as structured JSON with a pane_id of w1:p2 and agent_status: unknown. The addressing scheme is workspace:pane — readable, scriptable, stable.

Then I ran a command in that pane and read its output back:

herdr pane run w1:p2 "echo HERDR_REAL_TEST; sleep 4; echo FINISHED"
herdr pane read w1:p2 --source recent --lines 20

HERDR_REAL_TEST
FINISHED
mejba@Engrs-MacBook-Pro herdr-test %

Worth knowing: pane read takes a --source flag with four modes — visible for the current screen, recent for scrollback that accounts for wrapping, recent-unwrapped for logs where soft wrapping ruins your grep, and detection for the exact snapshot herdr's agent detection is evaluating. That last one is a genuinely thoughtful debugging affordance. When detection misfires, you can see precisely what herdr saw.

The blocking wait is the feature that matters

Here's the primitive that separates this from a nicer tmux. herdr lets one process block until another pane's agent reaches a given state.

I tested it directly. I flipped a pane to working, spawned a background job to flip it to idle after five seconds, and then 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 5 seconds with the triggering event:

{"event":"pane.agent_status_changed","data":{"pane_id":"w1:p2","workspace_id":"w1","agent_status":"idle","agent":"build-bot"}}

Sit with what that enables. You can write a shell script where Claude Code does the implementation, and the moment it goes idle, Codex automatically starts the review — no polling loop, no arbitrary sleep 300, no human watching a terminal. The --source custom:test flag means any process can report state, so you're not limited to the fourteen blessed agents. Your own build script can register as an agent and participate in the same orchestration graph.

I've written before about running multiple Claude Code agents in parallel with git worktrees, and the honest weak point of that setup has always been coordination — you get isolation for free, but sequencing agents means either babysitting them or writing brittle polling. herdr wait is the missing piece. herdr even ships worktree helpers directly (herdr worktree create --workspace-id w1 --branch worktree/api), which suggests the author hit the same wall.

If you'd rather have this kind of multi-agent orchestration designed and wired into your team's actual pipeline instead of assembled from shell scripts on a Saturday, that's the sort of build I take on — you can see my work at fiverr.com/s/EgxYmWD.

The crash test: what actually survives a server restart?

Now the test I opened with, in full.

The persistence claim is herdr's headline. The docs are more careful than the blog posts about it, and my results were more specific than either.

Before the crash, herdr api snapshot showed two panes, one tab, one registered agent:

panes: 2 tabs: 1 agents: 1
   w1:p1 term: term_656ea96f21af61 cwd: /private/tmp/herdr-test
   w1:p2 term: term_656ea98cdbbf02 cwd: /private/tmp/herdr-test

Then I killed it ungracefully — kill -9, not a clean shutdown — and restarted:

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 things happened, and the distinction between them is the whole story:

The layout survived. Two panes, one tab, correct working directories, correct structure. That part works exactly as advertised, even through a SIGKILL.

The processes did not. Every terminal_id changed. Those are new shells in the right directories, not resumed processes. If a test suite or a dev server had been running, it was gone.

The agent state did not. My registered agent went from one to zero. State registrations are in-memory and die with the server.

So the accurate mental model is this: detaching is lossless, crashing is not. When you detach with ctrl+b q, the server keeps running and every process stays alive — that's the strong persistence path, and it's the one you'll use daily. When the server dies, you get your furniture back but not your running work.

herdr has two mitigations, and you should know the defaults. Native agent session restore is enabled by default — it resumes agent conversations for supported agents using session references that the integration hooks reported, which is why installing those hooks matters more than it first appears. Pane screen history replay is disabled by default, and the stated reason is exactly right: pane output can contain secrets, tokens, and prompts. Turning it on means writing your terminal scrollback somewhere recoverable. Think carefully before you enable that on a machine that touches production credentials.

There's also an experimental herdr update --handoff that transfers running panes to a new server during an update, keeping processes alive. It only works with herdr's built-in updater — so if you installed via Homebrew like I did, you're likely outside that path.

herdr terminal multiplexer vs tmux vs zellij: where each one wins

For reference, the incumbents as of this writing: tmux 3.7b shipped July 1, 2026, and zellij 0.44.3 shipped May 13, 2026. Both are mature. Neither is going anywhere.

The project's own framing is unusually honest, and I think it's correct: tmux persists terminals; herdr persists agent workspaces and understands agent state. And against zellij: zellij is a modern terminal workspace; herdr is an agent multiplexer with state, waits, and orchestration.

Strip away the positioning and the real feature delta is narrow but sharp. All three run inside your existing terminal, keep persistent PTY sessions, and support detach and reattach over SSH. Only herdr does semantic agent state tracking, direct agent terminal attachment, and an agent-shaped API with read, send, wait, split, and attach as first-class operations. tmux and zellij give you terminal scripting; you could build state detection on top, and people have, but you'd be rebuilding this.

Here's my honest read on where each wins:

Choose tmux if you manage production servers, if you have a .tmux.conf you've tuned for years, or if stability outranks features. Eighteen years of muscle memory and a plugin ecosystem nothing else matches. Nobody ever got paged because tmux did something surprising.

Choose zellij if you want discoverability and a modern UX — it shows you what keys do what, uses a mode-based interface, and has a WebAssembly plugin system you can extend in any language. Version 0.44.0 added remote sessions and Windows support.

Choose herdr if you're regularly running three or more coding agents at once and losing time to the question which one is waiting on me right now? That's a real, specific, expensive problem, and this is currently the only tool that solves it natively.

If you're not running multiple agents concurrently, herdr is a worse tmux with fewer plugins and less history. The agent-state feature is the entire value proposition. No agents, no value.

What herdr gets wrong

I'd be doing you a disservice if I stopped at the good parts.

There is no sandboxing. This is the one that should give you pause. herdr is a multiplexer, not a security boundary. Every agent in every pane shares the same filesystem access as you do. If you're handing a socket API to autonomous agents so they can spawn more panes and run more commands, understand that you've built a convenience layer, not a containment layer. The blast radius of a misbehaving agent is your entire home directory.

Windows is beta, and the SSH story is broken there. The ConPTY backend doesn't currently support --remote, so remote attach over SSH isn't available on Windows. The cross-platform claim is real but asymmetric — Mac and Linux get the full feature set.

It's young. Version 0.7.4 is pre-1.0, the protocol is at version 16 and explicitly versioned because it's still moving, and the docs tell you to handle unknown response fields gracefully and read the release notes for breaking changes. That's a project being honest about churn. If you build serious automation on this API in July 2026, budget for maintenance.

The bus factor. This is essentially one full-time developer's project. That's produced remarkable velocity — and it's a concentrated risk if you're standardizing a team workflow on it. The AGPL-3.0 license is also worth a conversation with whoever handles legal at your company before it goes anywhere near a commercial product; a commercial license exists precisely because AGPL is a problem for some orgs.

The plugin marketplace is early. Plugins are local executables driven by a herdr-plugin.toml manifest with actions, event hooks, panes, and link handlers — a clean design that hooks events like worktree.created. But "marketplace" currently means sharing via GitHub repositories. Set your expectations accordingly.

Where this fits in a real workflow

I'm not ripping out my current setup. But I am keeping herdr installed, and here's the specific reason.

I went through something similar when CMUX turned my Mac into an agent command center — a different tool attacking the same mess from the GUI side. herdr's bet is the opposite one: stay in the terminal, add semantics instead of chrome.

My multi-agent pain has never been starting agents. It's the dead time — the minutes where an agent finished four minutes ago and I didn't notice, or worse, sat blocked on an approval prompt in a pane I wasn't looking at. When I wrote about Claude Code's Agents View dashboard, that was Anthropic solving this problem inside their own tool. herdr solves it across every tool, which is the version that actually matches how I work — I run Claude Code and Codex in the same repo most days, and no first-party dashboard is going to show me both.

The honest recommendation: install it, run one real project through it for a week, and pay attention to whether the state sidebar changes your behavior. If you find yourself checking it instead of cycling through panes, it's earned its place. If you forget it's there, you're not running enough agents for it to matter yet — and that's a fine answer.

Start here:

brew install herdr
herdr integration install claude
herdr integration install codex
herdr

Then, before you trust it with anything real, run the test I ran. Kill the server. See what comes back. Any tool that's going to hold your work in memory deserves to be asked what happens when it dies — and the answer should come from your terminal, not from a landing page.

Let's Work Together

Looking to build AI systems, automate workflows, or scale your tech infrastructure? I'd love to help.

• Fiverr (custom builds & integrations): fiverr.com/s/EgxYmWD
• Portfolio: mejba.me
• Ramlit Limited (enterprise solutions): ramlit.com
• ColorPark (design & branding): colorpark.io
• xCyberSecurity (security services): xcybersecurity.io