A coding agent, running inside one terminal pane, reads a CLI reference, then spins up two more agent panes of its own, hands each a task, and waits on their status before continuing. No human touched the keyboard between the first prompt and the final answer. That is the moment Herdr makes ordinary, and it reframes what a terminal multiplexer is for.
Figure 1 - The agent-callable session bus: A coding agent in one pane calls the Herdr CLI over a local Unix socket to spawn two more agent panes, inject prompts, and wait for each to report done. The session multiplexer becomes a programmable orchestration layer that agents themselves can drive. This is the tmux-as-MCP pattern.
Start with the pain, because everyone running long agent sessions has felt it. You kick off a task that will take 90 minutes. You walk away. You come back to find the agent hit a permission prompt at minute four and sat idle for the other 86, waiting for a keystroke you were never there to give. The work did not fail. It simply never happened, and nothing told you.
Herdr [1] fixes the layer where that failure lives. It is a terminal multiplexer built for AI agent workflows, and it adds the one thing tmux never had: awareness of what the agent inside each pane is actually doing. Panes report status. Blockers raise notifications. A local Unix socket exposes the whole session graph to any process smart enough to call it, including the agents themselves.
We have spent months building multi-agent pipelines on this site, and the session layer underneath them has always been the weakest link. Herdr is the first tool we have seen that treats that layer as a programmable substrate rather than a dumb grid of terminals.
The 86 idle minutes
The idle-agent problem is structural, not accidental. A long-running agent alternates between two states you care about: it is working, or it is stuck waiting on you. Plain tmux shows you neither. A pane is just a pane. To know whether an agent is grinding through a refactor or frozen on a permission prompt, you have to look, read the scrollback, and interpret it yourself. Across a dozen panes, that is a full-time job, and the whole point of running agents was to not have one.
Figure 2 - Where the time goes: A 90 minute session collapses to four productive minutes when a permission prompt lands early and nothing surfaces it. The agent is not broken. It is waiting, silently, for attention it has no way to request. This is the exact failure Herdr’s blocker status is built to catch.
The cost compounds when you run agents in parallel. Three agents working three features means three independent chances to stall on a prompt you cannot see. The more you scale out, the more of your day you spend babysitting terminals to confirm they are still moving. Concurrency without visibility is not leverage. It is just more surface area to watch.
KEY INSIGHT: The bottleneck in parallel agent work is not compute, it is attention. Any layer that tells you which panes need you, and which do not, converts babysitting back into leverage.
What Herdr actually is
Herdr (spelled h-e-r-d-r, no second ‘e’) is a single self-contained binary. It is written in Rust, weighs about 10 megabytes, and ships with zero dependencies [2]. There is no Electron shell, no cloud account, no background service phoning home. You install it with curl -fsSL https://herdr.dev/install.sh | sh, or through brew, mise, or cargo, and you have a working multiplexer in one step [1]. For a category of tool that increasingly means “sign up, install the desktop app, connect your account,” a 10 megabyte static binary is a genuine differentiator.
It is free and open source under AGPL-3.0-or-later, with an optional commercial license [2]. The project is maintained by Ogulcan Celik, and as of July 2026 the repository carries roughly 16,100 GitHub stars across 70 releases, with v0.7.3 shipping on July 7 [2]. The traction is worth citing plainly, because “a promising side project” and “a tool 16,000 engineers have starred” are different risk profiles when you decide what to build a workflow on.
On platform support, be precise. Mac and Linux are the stable targets, which is expected given the Unix socket at the core of the design. A Windows beta preview installer now exists as well (irm https://herdr.dev/install.ps1 | iex), added after the tool’s earliest demos, so the older “Unix-only, no Windows” framing is out of date [1]. Treat Windows as a beta preview rather than a peer platform, and treat WSL as unconfirmed until the docs say otherwise.
AI-aware status: idle, working, blocker
The feature that earns Herdr its “tmux for AI agents” label is per-pane status. Every pane running a coding agent carries one of three states [4]:
- Idle, the agent is waiting for input.
- Working, the agent is actively processing.
- Blocker, the agent has surfaced a question or permission prompt that needs you now.
When an agent finishes, Herdr fires a desktop notification so you can come back and continue. When an agent hits a decision point mid-run, it raises a blocker and pings you separately. You stop polling terminals and start responding to signals. The 86 idle minutes become an 86-second gap between the prompt landing and the notification pulling you back.
Figure 3 - The status lifecycle: Each agent pane moves between idle, working, and blocker. A finished run and a raised blocker both trigger desktop notifications, so a human is pulled in exactly when a pane needs attention and left alone the rest of the time. Attention becomes event-driven instead of poll-driven.
How Herdr knows a pane’s status matters, and this is where the demos have been misread. Herdr detects status two ways [4]. The first is lifecycle hooks, where the agent reports its own state directly to the socket. The second is a screen manifest, a set of TOML rules matched against a snapshot of the pane’s output. Per Herdr’s own agent docs, both Claude Code and Codex are screen-manifest detected, alongside GitHub Copilot CLI, Droid, Qoder, Cursor Agent, and OpenCode. The hook-based agents, the ones Herdr calls lifecycle authorities, are Pi, OMP, Kimi Code CLI, Hermes, and MastraCode [4].
That distinction kills a tempting but wrong story. In some early recordings, Codex status synced cleanly while Claude Code lagged, and the easy conclusion was “Codex has hooks, Claude does not.” It does not. Both are detected the same way, by reading the screen. Any difference on a given day was a rules-and-recording artifact between two screen-detected agents, not an architectural gap between the two tools. For Claude Code specifically, idle and working are detected reliably, while blocker detection is deliberately strict and can lag a few seconds before it fires [4]. Knowing that keeps you from chasing a phantom integration problem.
KEY INSIGHT: When a tool infers state by reading the screen, treat status timing as a detection heuristic, not a contract. Design your orchestration to tolerate a few seconds of lag on a blocker rather than assuming the signal is instant.
Where tmux stops and Herdr starts
None of this makes tmux obsolete. tmux remains an excellent general-purpose multiplexer, and Herdr borrows its keyboard-first, prefix-key model directly. The gap Herdr fills is narrow and specific: tmux has no idea that the process in a pane is an AI agent, so it cannot tell you whether that agent is working or stuck. Everything AI-aware is the addition.
| Capability | tmux | Herdr |
|---|---|---|
| AI status tracking (idle / working / blocker) | No | Yes [4] |
| Programmatic pane control | Via the tmux CLI | Via the herdr CLI and socket [3] |
| Remote attach without a manual SSH login | No | Yes, herdr --remote <host> [1] |
| Built-in browser for visual agent context | No | No |
| Persistence across terminal restarts | Yes | Yes |
| Windows support | Yes | Beta preview installer; Mac and Linux stable [1] |
Figure 4 - The delta, not a replacement: tmux and Herdr share the multiplexer core. Herdr’s additions cluster in one place: it knows a pane is running an agent, tracks that agent’s status, and exposes the session graph over a socket that programs can drive.
The honest caveat is that Herdr has no built-in browser, so agents that need visual context still reach for MCP tools or separate browser tooling. You can run Herdr inside tmux to borrow tmux’s browser, but doing so breaks Herdr’s own detach-and-attach persistence. Pick one model and commit to it.
The Unix socket as a programmable bus
Under the status layer sits the feature that changes the architecture: a local Unix socket that speaks newline-delimited JSON. Any process on the machine, including a running coding agent, can reach that socket through the Herdr CLI and drive the session [3]. This is the substrate that turns a multiplexer into an orchestration layer.
The command surface is broad and documented. From the socket API reference [3]:
herdr workspace create|list|get|focus|rename|move|closemanages workspaces.herdr tab create|list|get|focus|rename|move|closemanages tabs.herdr pane split|run|read|resize|swap|zoommanages panes. For example,herdr pane split w1:p1 --direction rightsplits a pane,herdr pane run w1:p2 "npm test"runs a command in one, andherdr pane read w1:p2 --source recent --lines 50reads output back.herdr agent list|get|send|wait|startcontrols agents at the agent level.herdr wait agent-status w1:p1 --status doneblocks until a pane’s agent reaches a state, with--status blockedas the other common target.herdr session attach <name>andherdr session listmanage the detach-and-attach persistence layer.
Beneath the CLI, the socket exposes more than 70 raw methods, including pane.send_keys, pane.send_text, pane.wait_for_output, and events.subscribe [3]. The three verbs that matter for orchestration are spawn, inject, and wait: create a pane, send it a prompt, and block until it reports a result. Those three are enough to build a control loop.
Figure 5 - Spawn, inject, wait: The Herdr socket reduces to three orchestration primitives. A caller creates a pane, injects a prompt or command, and waits on the pane’s status. Any process that can open the socket, a shell script or a coding agent, can compose those primitives into a pipeline. That composability is the whole architecture.
A word of discipline on commands. The exact keystrokes shown in Herdr’s demos are demo artifacts, and command names have shifted across releases. Trust the socket API docs for canonical command and flag names, and treat any string you saw typed in a video as illustrative, not authoritative.
The wow moment: agents spawning agents
Put the socket and the CLI together and you get the demonstration that made Herdr circulate. A driver instructed a Codex agent to read the Herdr CLI documentation, then use herdr pane to spawn two more Codex instances, hand each one a lookup task, and wait on their results before answering [3]. The demo worked, imperfectly. A workspace mix-up spawned an extra instance, but the correct answers came back. The imperfection is the point: this is real, and it is early.
The architectural claim underneath the demo is the durable part. A coding agent in one pane can use the Herdr CLI to create additional panes, inject prompts, and monitor status. The agent is not just running in the session. It is programming the session. Herdr becomes an agent-callable bus, and the pattern generalizes: pane isolation with programmatic control, reachable from inside any agent that can shell out. We have called this tmux-as-MCP, because the session multiplexer starts to behave like a tool surface an agent invokes rather than a window manager a human arranges.
KEY INSIGHT: The unlock is not that agents can run in parallel panes. It is that an agent can create and coordinate those panes itself, over a socket, turning the session layer into a tool it calls rather than an environment a human sets up.
Substrate versus orchestrator
The temptation, once you see agents spawning agents, is to make the session layer do everything. Resist it. The clean architecture keeps two responsibilities separate. Herdr is the substrate: persistent, isolated panes with status and a socket. The orchestrator is a layer above it that decides which specialists to spawn, hands them work, polls their status, and assembles their output.
For our own pipelines, the recommended orchestrator is the Dotzlaw bootstrap framework running on top of Herdr. The orchestrator lives in one pane. It calls herdr pane split to launch specialist worker panes, one per role, each a separate coding agent with its own context and its own tool connections. It injects each specialist’s brief, then polls herdr wait agent-status on each pane and reads results back over the socket when a pane reports done or blocked. Herdr guarantees the isolation and the signaling. The bootstrap framework owns the routing and the sequencing. Prior art exists for this shape, and existing orchestration frameworks occupy the same layer, but the division of labor is the lesson: substrate below, orchestrator above.
Figure 6 - Two layers, two jobs: Herdr is the session substrate that provides isolated panes, status, and a socket. The bootstrap framework is the orchestrator above it, spawning one specialist pane per role and polling each pane’s status to drive the pipeline. Keeping the layers distinct keeps both replaceable.
That separation is what the context-isolation guarantee buys you. Each pane is a separate process, so a specialist working one domain cannot pollute the context of a specialist working another. They are siblings in the session graph, not threads sharing a window. It is the same clean-handoff principle we argued for in Multi-Agent Pipelines in Claude Code [6], now pushed down into the session layer itself.
Wrap the CLI in a skill
The demo also carried a piece of advice worth taking literally. Rather than teaching an agent the Herdr CLI fresh every time, have it read the documentation once and package the spawn-and-wait procedure as a skill, so you have a repeatable primitive to spin up panes on demand. Once that skill exists, every orchestration run reuses it instead of rediscovering the command surface.
Figure 7 - A skill as a spawn primitive: Wrapping the Herdr spawn-inject-wait sequence in a skill turns a multi-step CLI dance into one callable primitive. The orchestrator invokes the skill instead of reconstructing the commands, which makes the spawn behavior consistent, versioned, and reviewable across runs.
This is the same skill-packaging discipline we apply everywhere in the harness. A raw CLI is powerful and fiddly, a skill wrapping that CLI is powerful and repeatable. When your orchestrator’s most important move is “spawn a specialist and wait for it,” that move deserves to be a named, tested primitive rather than a string of commands the agent guesses at each time.
Remote attach across machines
The session layer extends past one machine. herdr --remote <hostname> reads your SSH host config and attaches to an existing Herdr session on a remote box without making you run a manual SSH login first [1]. Start a multi-hour run on a headless Linux server at home, leave, connect from a laptop elsewhere, and resume the live session with one command.
Figure 8 - One session, many front ends: A persistent Herdr session runs on a remote server. herdr --remote <host> attaches to it from any machine without a manual SSH handshake, so the same long-running agent session follows you between devices. The work lives on the server; the terminal you attach from is disposable.
The field test: a raw-tmux fleet at scale
Herdr is young, so the most useful stress test of the pattern comes from someone who built it the hard way. Kyle Jaejun Lee, an engineer at KRAFTON, runs a personal fleet of Claude Code agents across three machines, a MacBook plus two always-on headless Linux boxes, using plain tmux and a custom harness rather than Herdr [5]. He is clear in the talk that this is his own daily-driver side project, not a KRAFTON product and not a demo assembled for the stage. That makes his account a first-person record of what breaks when you push a raw tmux session bus past a single machine, which is exactly the ground Herdr is trying to pave.
Three of his failures are worth recording, because they map directly onto what a purpose-built substrate has to solve [5]:
tmux capture-panedegrades under pane overcrowding. As managers spawned more worker panes into one window, the panes shrank untilcapture-pane, the exact tool he used to read a pane’s output programmatically, could no longer pull anything meaningful out. The orchestration model held. The tooling hit a hard limit on how many live panes one window can carry before programmatic reads break down.- Cross-workspace git-credential collision. The plan was a clean one-to-one mapping of credential to workspace. In practice credentials crossed over and bound to the wrong workspace. The fix was a fully separated environment per workspace, with no shared credential state at all.
- OOM and swap exhaustion from stacked agent and MCP processes. As sessions piled up on one machine, memory filled, swap filled, and in his words “the sessions just stacked up until the machine couldn’t breathe” [5]. That is a hard resource ceiling on how many concurrent agent-plus-MCP stacks one box can hold, independent of whatever session software sits on top.
Figure 9 - What breaks at fleet scale: A raw tmux agent fleet across three machines surfaces three concrete failures: capture-pane reads degrade as panes overcrowd a window, git credentials collide across workspaces, and stacked agent-plus-MCP processes exhaust memory and swap. Each is a resource, isolation, or coordination limit a purpose-built substrate must own.
Two coordination details round out the account. Lee routed all review requests and status through Discord, one bot per machine, turning his phone into the remote control for the whole fleet [5]. To move context between machines, he pushed the context files over git, then used tmux send-keys over SSH to poke the destination session into pulling. Two machines writing to one shared directory produced silent divergence, which he fixed by binding state to per-machine directories and letting shared state change only through a pull request [5]. His closing framing is that these are the questions Kubernetes already answers, and his direction is to build an orchestration manager on top of that layer instead of reinventing it.
KEY INSIGHT: Every failure mode of a raw multi-machine agent fleet is a resource, isolation, or coordination problem that infrastructure engineering already named. The session substrate should own isolation and signaling so your orchestrator can spend its attention on routing, not on reinventing credential scoping and memory limits.
Conclusion
The session layer under your agents has been invisible, and invisible layers are where time quietly disappears. Herdr makes that layer legible. Per-pane status turns silent stalls into desktop notifications, a self-contained Rust binary keeps the tool out of the cloud-account trap, and a documented Unix socket turns the multiplexer into something an agent can program, which is the shift that matters most.
The architecture to carry forward is two clean layers. Herdr is the substrate: isolated panes, AI-aware status, and a socket that exposes the session graph. Your orchestrator, the bootstrap framework in our case, sits above it, spawning specialists and polling their status over that socket, with the spawn-and-wait move wrapped in a skill so it stays repeatable. Kyle Lee’s raw-tmux fleet shows what you inherit if the substrate does not carry its weight: overcrowded pane reads, credential collisions, and machines that cannot breathe. When the layer that runs your agents becomes a layer your agents can drive, orchestration stops being something you supervise and starts being something the system does on its own.
The Series
This is the opening article of the Session Bus & Orchestration Substrate thread, a single-part sub-series for now:
- Herdr and Parallel Agent Sessions: The Tmux-for-AI-Agents Pattern (this article). How an AI-aware multiplexer with a programmable Unix socket becomes the session substrate that agent orchestrators run on top of.
References
[1] Herdr, “Herdr: one terminal for the whole herd,” Official site, 2026. https://herdr.dev/
[2] O. Celik, “ogulcancelik/herdr,” GitHub, 2026. https://github.com/ogulcancelik/herdr
[3] Herdr, “Socket API,” Herdr Documentation, 2026. https://herdr.dev/docs/socket-api/
[4] Herdr, “Agents,” Herdr Documentation, 2026. https://herdr.dev/docs/agents/
[5] K. J. Lee, “I Run a Fleet of AI Agents Across Three Machines. Here’s What Broke,” AI Engineer, Jul 2026. https://www.youtube.com/watch?v=4kYl2_mqmnQ
[6] G. Dotzlaw, K. Dotzlaw, and R. Dotzlaw, “Multi-Agent Pipelines in Claude Code: Researcher, Architect, Developer, Reviewer,” 2026. /insights/claude-code-03-multi-agent-pipelines/
Building production AI, or modernizing a legacy system?
That is the kind of work we do at Dotzlaw Consulting. Book a free 20-minute intro call and tell us what you are trying to build, or what is slowing you down.