What Is herdr? The 'tmux for Agents' That Runs Multiple Coding Agents in One Terminal¶

For / Key Points

For: Developers running multiple CLI agents such as Claude Code and Codex who spend too much time polling terminal panes.

Key Points:

herdr adds blocked / working / done / idle rollups to persistent terminal sessions
Claude Code and Codex remain screen-detected because their hooks do not cover the full lifecycle
the Socket API enables waits and orchestration, but herdr is still a pre-1.0 v0.7 project

Run Claude Code and Codex in four panes and the next bottleneck is not compute. It is the attention spent checking which pane needs approval and which one has finished. herdr moves that polling work into a terminal sidebar.

This article asks one question: is herdr merely a different tmux interface, or does it add a new control layer for multiple agents?

herdr Solves Attention Allocation, Not Agent Launching¶

herdr is a multiplexer that keeps each agent in a real terminal pane while collecting its state in one view. It ships as a single Rust binary rather than an Electron app or hosted dashboard. It organizes work into workspaces, tabs, and panes, while a background server keeps processes alive after the client closes¹.

tmux and Zellij can also persist panes. They do not know whether Claude Code inside a pane is waiting for approval. herdr classifies agents as blocked, working, done, or idle and rolls that state from panes into tabs and workspaces. If one agent is blocked, the workspace display identifies where intervention is needed².

The distinction is not pane splitting. It is whether agent state can become a control signal.

Option	Persistent sessions	Agent state	Primary environment
tmux / Zellij	Yes	Unaware	Terminal and SSH
Desktop agent manager	Product-dependent	Aware	Machine running the GUI
herdr	Yes	Four-state rollup	Terminal and SSH

How can it identify those states without modifying every agent?

State Detection Has Two Authorities¶

herdr first identifies the foreground process in each pane. It then assigns one status authority to that pane: either lifecycle reports from an integration or rules applied to a snapshot from the bottom of the live terminal buffer².

Lifecycle authority: Pi, OpenCode, Hermes Agent, and similar agents can use hook or plugin reports as the sole state source when a complete integration is active
Screen authority: Claude Code, Codex, GitHub Copilot CLI, and others are evaluated against TOML rules using the live bottom-buffer snapshot

Claude Code and Codex do have integrations, but those integrations mainly provide session identity. Their hooks can miss permission results, Escape interruptions, and other transitions. herdr therefore deliberately keeps screen manifests authoritative for their state².

The blocked rule is conservative. A known agent falls back to idle when the screen does not match a known approval, question, or permission UI. A newly changed prompt can therefore appear idle until the manifest catches up. Remote manifests update from herdr.dev, and this command shows the evidence behind a decision:

herdr agent explain w1:p1

Zero configuration does not mean perfect classification. For screen-detected agents, the sidebar is best treated as an attention sensor, not an audit log.

A Three-Command Minimal Setup¶

On Linux or macOS, installation through the Claude Code integration takes three commands³.

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

Start claude or codex normally in any pane and its state appears in the sidebar. The default keyboard model uses a tmux-style prefix: Ctrl+b q detaches, and running herdr again reattaches. Homebrew users can install it with brew install herdr¹.

The same model works on a remote host. The official site presents SSH reattachment from a phone and herdr --remote as primary workflows⁴.

Persistence alone would not distinguish herdr from tmux. The boundary-crossing feature is an API that can wait on semantic state.

The Socket API Turns Monitoring Into Orchestration¶

herdr exposes newline-delimited JSON over a local socket. Workspace operations, pane reads, agent-state waits, and event subscriptions are available through CLI wrappers or the raw protocol⁵.

herdr agent start reviewer --cwd ~/project --split right -- claude
herdr wait agent-status w1:p1 --status done
herdr pane read w1:p1 --source recent --lines 50

That is enough to script “wait for agent A, read its output, then start agent B.” The API also exposes pane.agent_status_changed subscriptions, and the project ships a reusable SKILL.md that teaches agents how to operate herdr themselves⁵⁶.

There is an important boundary. wait agent-status waits for herdr's semantic classification, not for arbitrary command completion. If screen detection falls back to idle, automation receives that same judgment. API availability and state accuracy are separate properties.

Adoption Criteria and Pre-1.0 Limits¶

herdr fits environments that regularly run several CLI agents, work over SSH, and want to automate state-dependent handoffs. A single foreground agent often does not justify another multiplexer layer.

As of July 16, 2026, the latest stable release is v0.7.4, so the project remains pre-1.0⁷. Native Windows support is an experimental preview beta built on ConPTY rather than the Unix PTY model, and it does not promise full Linux/macOS parity⁸. Screen-authority agents also remain exposed to detection lag when their terminal UI changes.

The project uses a dual-license model: AGPL-3.0-or-later for open-source use and commercial licenses for organizations that cannot comply with the AGPL¹. Organizations planning internal distribution, network deployment of modifications, or other nontrivial use should review the applicable obligations before adoption.

Summary¶

herdr adds agent-state rollups to persistent tmux-style terminal panes
Claude Code and Codex remain screen-detected, so blocked detection is a signal rather than a guarantee
the Socket API moves status checks from human polling into scriptable waits

The deeper issue is not which multiplexer wins. If agents eventually emit standardized lifecycle events, screen inference can disappear. herdr is a practical bridge for the period in which the terminal screen is still the only common state surface.