Herdr Agent Multiplexer: Terminal Control Surface for Agents
Herdr agent multiplexer is the useful search phrase, but the stronger operator frame is narrower: Herdr is a terminal control surface for running and supervising many coding-agent panes without turning the workflow into a desktop app or a pile of anonymous tmux splits.
That distinction matters because the next wave of agent tooling is not only about better models. It is about the layer around the models: where the panes live, how sessions survive disconnects, how blocked or done agents become visible, how another script can read output, and which controls are safe enough to automate.
This is a source-read-only Starkslab note. It is based on the public Herdr GitHub repo, the current Herdr docs, and the accepted Starkslab source-read memo for the same repository.
Proof state: source-read-only.
What Starkslab read: Herdr README, Cargo metadata, public docs for concepts, installation, agents, integrations, session state, persistence/remote access, CLI reference, socket API, and the local starkslab/research/2026-05-29-herdr-terminal-agent-multiplexer-source-read.md memo.
What Starkslab did not run: clone, install, Homebrew, Nix, curl install script, release binary, cargo build, cargo test, herdr, server/client launch, workspace creation, tab or pane mutation, direct attach, remote attach, socket API request, integration install, hook install, SSH attach, benchmark, security review, or production workflow validation.
What this page can prove: source-visible architecture and operator questions around terminal multiplexing for agents.
Blocked claims: this page cannot prove Herdr is safer, faster, better than tmux, production-ready, secure, reliable in real workloads, broadly adopted, or suitable for unattended agent control.
What this page covers:
- what Herdr is;
- where the terminal control surface lives;
- why agent state changes the multiplexer job;
- what the socket API makes possible;
- what can break when terminal state gets mistaken for workflow authority;
- how Herdr fits into Starkslab's AI Agent Tools and Build AI Agent clusters.
For the broader category map, read The Coding Agent Harness Layer. For a worktree-specific cockpit, read dmux Shows the Useful Coding-Agent UI Is a Worktree Cockpit. For review discipline around agent work, read AI Coding Agent Workflow.
What is the Herdr agent multiplexer?
Herdr is a terminal-native workspace manager for AI coding agents.
The public README describes it as an agent multiplexer that lives in your terminal: workspaces, tabs, panes, mouse-native splitting, detach/reattach, agent state, real terminal views, and no Electron-style wrapper. The source-level readback supports the core shape. Cargo.toml names the package herdr, describes it as a "terminal workspace manager for AI coding agents," and lists a Rust TUI/runtime stack around ratatui, crossterm, portable-pty, tokio, serde, and serde_json.
That makes Herdr different from a coding agent. It does not appear to be the model runtime, the planner, the review system, or the merge authority. It is the terminal/session layer around external tools such as Claude Code, Codex, OpenCode, Hermes, Qoder, and similar command-line agents.
The clean mental model is:
operator
-> Herdr client
-> Herdr background server
-> workspaces, tabs, panes, named sessions
-> real PTY-backed shells or agent CLIs
-> process/screen heuristics plus optional integration reports
-> sidebar state, CLI commands, socket API, direct attach, and waits
That is why this page belongs in the AI Agent Tools cluster. The useful question is not "should you use Herdr tomorrow?" The useful question is what Herdr makes visible about the terminal-agent control layer.
Where does the Herdr agent multiplexer control surface live?
The control surface lives in the split between Herdr's background server, attached client, real terminal panes, agent detection, CLI wrappers, and local socket API.
The public concepts docs define the basic units:
- a workspace is the top-level project container;
- a tab is a layout inside a workspace;
- a pane is a real terminal process that Herdr renders and preserves across client detach;
- an agent is a process Herdr recognizes inside a pane;
- a session is a persistent Herdr server namespace.
The session state docs then separate the persistence paths. Normal detach is strongest because the server keeps the original panes, shells, agents, tests, and commands alive. Snapshot restore after server restart brings back layout and cwd, but not arbitrary running processes. Native agent session restore only applies when supported integrations report enough session reference data. Pane history is optional and explicitly sensitive because terminal output can contain secrets.
That taxonomy is the important part. It avoids the fake promise that "session restore" always means the same thing.
Source metadata readback:
package: herdr
description: terminal workspace manager for AI coding agents
license: AGPL-3.0-or-later
stack: Rust, ratatui, crossterm, portable-pty, tokio, serde_json
current public docs: herdr.dev/docs
Those facts support a narrow claim: Herdr is a real terminal multiplexer/control-surface project with an agent-aware layer. They do not prove runtime quality.
Why does agent state change the terminal multiplexer job?
A normal terminal multiplexer answers one question: where are my terminals?
An agent-aware terminal multiplexer has to answer a harder question: which terminal needs a decision?
Herdr's docs and README describe four main agent states: blocked, working, done, and idle. The agent docs explain that Herdr combines foreground process detection, terminal output heuristics, and optional integration state reports. The integrations docs show the stronger path: hooks or plugins can report semantic state directly to Herdr's local socket.
That matters because the operator problem is not just layout. The operator problem is attention.
If ten panes are running, "pane exists" is weak information. "This one is blocked," "this one is working," and "this one is done but unseen" are much more useful.
The same lesson already shows up in Starkslab's own factory. A Linear issue, a worker pane, or a note source file is not enough. The system needs state: Todo, In Progress, Human Review, Rework, Done, missing artifact, source conflict, live verified, indexing pending. Herdr exposes a terminal-native version of that pattern for agent panes.
The caveat is just as important: state detection is not workflow authority.
A pane can look idle while a background child process runs. A terminal screen heuristic can stale-match old output. An integration can be absent, outdated, or reporting stale state. Herdr exposes state; it does not prove the underlying work is correct.
What can agents and scripts do through Herdr?
The socket API is the clearest reason Herdr is useful as article stock.
The socket API docs describe newline-delimited JSON over a Unix domain socket, with CLI wrappers for common operations. The control surface includes workspaces, tabs, panes, agents, waits, events, integrations, and server lifecycle.
The CLI reference shows the same shape in shell form:
herdr workspace create --cwd ~/project --label api
herdr tab create --label logs
herdr pane split 1-1 --direction right
herdr pane run 1-2 "npm test"
herdr pane read 1-2 --source recent --lines 50
herdr wait agent-status 1-1 --status done
Those commands are not presented here as a tutorial. Starkslab did not run them. They matter because they name the control primitives.
A useful harness needs more than "launch another terminal." It needs to create the right surface, put work in the right place, read what happened, wait for signals, and hand control back to an operator. Herdr's API gives a terminal-native vocabulary for that loop:
- create a workspace;
- split a pane;
- run a command;
- read visible or recent output;
- send text or keys;
- wait for output or agent state;
- attach directly to one agent terminal;
- let integrations report state.
That is why Herdr belongs near What Is a Coding-Agent Control Plane?. The primitives are not the same, but the operator problem is: turn hidden capability into named controls.
What does Herdr get right?
Herdr gets the stack boundary right.
It does not pretend every coding agent should become a web app. It keeps the operator inside a terminal and adds structure: workspaces, tabs, panes, sidebar state, mouse-native layout, direct attach, remote attach, and API access.
The strongest ideas are portable:
- real PTY-backed panes, not interpreted agent cards;
- a server/client model so panes can survive client detach;
- named sessions as separate runtime/socket namespaces;
- visible agent-state rollups across panes and workspaces;
- CLI and socket controls for read, send, split, wait, and start operations;
- integration events as a stronger state source than screen scraping alone;
- explicit docs for what survives detach, restart, native restore, and handoff;
- optional pane history treated as secret-sensitive, not enabled casually.
That last point is underrated. Terminal history is often full of tokens, URLs, paths, prompts, command output, stack traces, and account state. A tool that says "history is useful, but sensitive" is already closer to operator-grade than a tool that stores everything by default and calls it memory.
For builders, the Build AI Agent lesson is direct: if your agent system runs inside terminals, build the terminal substrate deliberately. Do not rely on a loose collection of shells, screenshots, and hope.
What can go wrong when you generalize Herdr?
The failure mode is over-reading the surface.
Herdr can make terminal agents visible. That does not make every visible agent safe to control.
The risk classes are different:
| Capability | Operator meaning | What this source read cannot prove |
|---|---|---|
| Read pane output | Observation surface | That output is complete, current, or secret-safe |
| Wait for agent state | Coordination signal | That state detection is correct in messy runs |
| Send keys or text | Direct control | That the target pane is safe to mutate |
| Run commands in panes | Execution authority | That the command is scoped or reversible |
| Install integrations | Stronger semantic state | That hooks are compatible or secure today |
| Remote attach | Work where the code lives | That the network/security posture is acceptable |
| Worktree commands | Workspace organization | That repo cleanup, merge, and review are handled |
That table is not a criticism. It is the evidence boundary.
Herdr exposes useful controls. Starkslab's rule is that useful controls still need policy around them. A local socket API is powerful. A terminal pane can hold credentials. A direct attach can collide with another operator. A remote session can carry host trust assumptions. A worktree can be dirty or destructive.
The Herdr agent multiplexer is interesting precisely because it makes those questions concrete.
How should operators evaluate Herdr before using it?
Evaluate Herdr as a terminal substrate, not as an autonomous agent system.
The first validation pass should be bounded:
- Pin the Herdr release or source version.
- Use a disposable repo with no production secrets.
- Start with one known coding-agent CLI already configured outside Herdr.
- Verify detach and reattach with a harmless long-running command.
- Inspect whether agent state reflects blocked, working, done, and idle accurately.
- Test
pane readandwait agent-statuson non-sensitive output. - Install one integration only after reading what it writes and where.
- Keep
pane send,pane run, direct attach, remote attach, and worktree removal out of autonomous flows until policy is explicit. - Review session files and history settings before using Herdr on secret-bearing work.
- Decide what evidence would be enough to call it useful in your real workflow.
That is the practical answer to the search intent. A terminal multiplexer for agents is not valuable because it sounds futuristic. It is valuable if it helps the operator see state, preserve sessions, inspect output, and make decisions without hiding risk.
Where does Herdr fit in the Starkslab stack?
Herdr is a support page for the AI Agent Tools cluster.
It strengthens the same route as The Coding Agent Harness Layer, but it should not compete with that owner page. The owner page explains the category above coding-agent CLIs. This page gives a concrete tool-name example: terminal-native multiplexing with agent state and machine-readable controls.
It also pairs cleanly with dmux. dmux is more about prompt, branch, worktree, tmux pane, agent launch, and merge or PR closeout. Herdr is lower in the stack: persistent terminal server, panes, tabs, sessions, state rollups, socket API, direct attach, and integrations. One is a worktree cockpit pattern. The other is an agent-aware terminal substrate pattern.
For Build AI Agent readers, the lesson is architectural:
If agents run in terminals, the terminal layer becomes part of the agent system.
For OpenClaw readers, the lesson is complementary. OpenClaw and Symphony own governed context, artifacts, memory, queue state, review, and publication boundaries. Herdr would sit lower: a way to make local terminal agents visible and controllable. It does not replace the operating system around those agents.
The next useful click depends on the reader's question:
- if you need the category map, read The Coding Agent Harness Layer;
- if you need the review loop, read AI Coding Agent Workflow;
- if you need skills, MCP, config, and safety gates, read What Is a Coding-Agent Control Plane?;
- if you need a concrete worktree cockpit contrast, read dmux Shows the Useful Coding-Agent UI Is a Worktree Cockpit;
- if you need protocol-mediated control context, read How to Run Codex and Claude Code Through OpenClaw with ACP.
The conclusion is intentionally bounded. Herdr is useful Starkslab evidence because it shows the terminal-native version of the control-surface problem. The Herdr agent multiplexer does not prove terminal agents are safe to automate. It proves the terminal layer now needs state, persistence, read/send/wait APIs, and clear authority boundaries.