herdr Makes Every Agent Pane Scriptable. That Is How People Are Running Fleets Now.

TL;DR

herdr is an open-source terminal multiplexer rebuilt for the age of agents. Think tmux, except every workspace, tab, and pane is a first-class object you can drive from a CLI and a JSON socket API, and it understands whether the agent inside a pane is idle, working, blocked, or done. That single change flips terminal orchestration on its head: an orchestrator agent can boot a fleet of coding agents, read each one's screen, message any of them, and block until they finish, with no human paste-shuttling between windows. The tagline, "one terminal for the whole herd," is doing a lot of honest work. Below is the mental model and the orchestration patterns people are actually running on top of it, as of herdr v0.7.3.

Why a multiplexer, and why now

The bottleneck in multi-agent work is you. If shipping with ten agents means eyeballing ten terminals and hand-pasting prompts, your fleet moves at human speed no matter how fast the models are. The old line from the agentic-engineering crowd is that an agent you cannot see is an agent you cannot improve. The corollary herdr adds: an agent you cannot script is an agent you cannot scale.

tmux can already split panes and fire send-keys, so why a new tool? Because tmux sees bytes. It will happily shove keystrokes at a pane and capture whatever text scrolls back, but it has no idea whether the thing in that pane is a shell, a build, or a coding agent that is halfway through editing a file and waiting on your approval. herdr's bet is that the terminal itself should be a programmable service that knows what an agent is doing, not just what it printed.

The mental model: session, workspace, tab, pane

herdr nests four things, and every layer has a CLI verb. A session is the durable root; it survives disconnects, so you can detach on the devbox and reattach from your phone over SSH mid-run. Inside it, a workspace is where people put one team of agents. A workspace holds tabs, and a tab holds panes. A pane is one agent.

Most people who run fleets put one team per workspace and one agent per pane, then keep the team lead on the left and its workers on the right. You look at whatever level gets the job done without losing the ability to drop into a single worker and read exactly what it is thinking.

The control loop: four verbs

Driving herdr programmatically comes down to a tiny loop: send input, read the screen, open or close surfaces, and wait. The input side has a gotcha worth knowing. Coding-agent TUIs like Claude Code and Codex swallow the atomic Enter that pane run sends, so for an agent prompt you use pane send-text to type the message and then a separate pane send-keys Enter to submit it. Reading uses pane read --source visible for the current rendered screen, not the wrapped scrollback.

The reason this feels different from tmux scripting is the last step. Instead of busy-polling a pane and grepping its output for a prompt, herdr exposes wait agent-status, which blocks until the agent in that pane flips to idle, blocked, or done. It is the difference between a manager who keeps walking desk to desk asking "done yet?" and one who just gets a tap on the shoulder when the work is finished. Under the hood every pane is reachable through a JSON socket API, so in practice each terminal has a phone number the orchestrator can call.

What herdr knows that a raw multiplexer does not

The load-bearing feature is semantic agent state. herdr ships integrations for the common harnesses (Claude Code, Codex, OpenCode and others) that report each agent's real status back into the multiplexer as idle, working, blocked, or done. So the orchestrator is not guessing from screen scrapes; it can list its fleet and see, at a glance, who is still chewing, who is stuck waiting on input, and who has finished. That status is also what wait and the completion notifications key off, which is what makes hands-off orchestration possible in the first place.

The patterns people are running

Give builders a programmable, agent-aware terminal and a handful of layouts show up again and again.

Three-tier orchestration

The favorite shape is orchestrator, leads, workers. A top-level orchestrator prompts a row of team leads, and each lead prompts its own specialized workers (a planner, a builder, a tester). It reproduces a clean org chart without the usual downside, because the communication channel underneath is flat: any agent can message any other agent directly through its pane, so a worker can ping a peer without routing back up through the boss.

The fleet race

When production is down and you need a fix yesterday, people fan the same task out to a fleet of different agents and take the first correct answer. You spin up Claude Code, Codex, and a couple of local models on the same needle-in-a-haystack search, then wait on the whole group and grab whoever crosses the line first. Different models have different strengths, so throwing varied intelligence at one problem tends to beat one agent iterating, provided you are willing to pay for the compute.

Wait-driven, not babysat

The thread through all of it is that the orchestrator sleeps on wait agent-status and completion notifications instead of you staring at screens. You can be deep in another workspace and get pinged the moment a fleet finishes. That is the payoff of the terminal knowing agent state rather than raw output.

Worktree isolation and one-command relaunch

For fleets that write code in parallel, herdr treats git worktrees as first-class: worktree create --branch gives each agent its own checkout so parallel edits do not collide on the same working tree. And because the whole thing is scriptable, people wrap team startup in a single command, so booting your thousandth run of a five-agent team is one keystroke, not five minutes of setup.

A worked example: two teams, one coffee break

Concrete beats abstract, so here is the whole thing in a real terminal. Ghostty is just the glass: herdr is a TUI that runs inside any terminal you like (Ghostty, Kitty, iTerm2, Windows Terminal), and Ghostty's GPU rendering only makes a wall of live agent panes pleasant to stare at. Nothing below is Ghostty-specific. You open Ghostty, type herdr, and the herd's session comes up inside it.

Where does the orchestrator live? In one pane. It is an ordinary Claude Code session sitting in a workspace you might label mission-control, and it has no special privileges. Its entire edge is that the herdr binary is on its PATH, so every command below is just a line it runs with its normal shell tool. That is the trick behind this post's title card: agents orchestrate agents because commanding the herd is only ever a shell command away. You sit one level up, watching from Ghostty, free to drop into any pane with a keystroke when you want to see what a worker is actually thinking.

The job: ship a small feature and get a security read on the same repo at the same time. So the orchestrator stands up two teams, one per workspace.

Step 1: stand up the teams

From the mission-control pane, the orchestrator creates a workspace per team and starts the agents inside it. The lead lands first, then splits off its workers:

# the kitchen: a lead plus three specialized workers
herdr workspace create --label kitchen --focus
herdr agent start kitchen-lead -- claude
herdr agent start planner --split right -- claude
herdr agent start builder --split down  -- codex
herdr agent start tester  --split down  -- claude

# the inspector: two agents racing the same scan on different models
herdr workspace create --label inspector --focus
herdr agent start sniff-opus -- claude
herdr agent start sniff-glm  --split right -- opencode

Six agents, two workspaces, and every one of them is now a named target you can talk to. An agent orchestrator that wants to be deterministic reads the exact IDs back from herdr workspace list, which is JSON; the labels above work as targets either way.

Step 2: hand out the briefs

Prompting an agent TUI is send-the-text then a separate Enter, but the agent send verb wraps both, so the orchestrator just talks to each team by name:

herdr agent send kitchen-lead "Ship a GET /roast endpoint that returns a random good-natured roast as JSON. Split it up: planner drafts the spec, builder implements, tester writes and runs the tests. Report back when it is green."
herdr agent send sniff-opus "Find the top 3 real security issues in this repo. Fastest solid answer wins."
herdr agent send sniff-glm  "Same brief as the other inspector. Race them."

None of this is top-down-only. When the builder finishes wiring the route, it does not report back up through the lead to reach the tester; from inside its own pane it just runs herdr agent send tester "route is live on localhost:8080/roast, start hammering it". That is the flat mesh from the earlier diagram, in one line.

Step 3: wait, then plate

Now the orchestrator does the one thing that makes the whole setup hands-off: it blocks. Instead of watching screens, it waits for each team to go idle, then reads the result straight off the pane:

herdr agent wait kitchen-lead --status idle --timeout 600000
herdr agent read kitchen-lead --source visible --lines 40

herdr agent wait sniff-opus --status idle --timeout 300000
herdr agent read sniff-opus --source visible --lines 20

The moment a team goes idle a herdr notification fires, which is your cue that there is something worth looking at. You spun up six agents, typed three briefs, and went to refill your coffee. By the time you are back, one inspector has already beaten the other to the punch and the kitchen is plating a tested endpoint whose entire job is to roast you back. The only thing you actually did was decide what the herd should chew on.

The catch

herdr is young. It is at v0.7.3, Windows support is still a beta preview (Linux and macOS are the stable targets), and agent-status detection can misfire: a notification event fires but the orchestrator does not always register it cleanly, which means part of teaching your agents to use the tool is teaching them to handle a missed wake-up. None of that is fatal, and the programmability is the point. Just know that hands-off orchestration is only as reliable as the status signal underneath it, and budget for the fact that a fleet of frontier agents burns tokens at a rate a single agent never will.

Key Takeaways

• herdr is a programmable, agent-aware multiplexer. Every session, workspace, tab, and pane is a CLI and JSON-socket object, so agents can orchestrate the terminal itself.
• Semantic agent state is the differentiator. It tracks idle, working, blocked, and done per pane, which raw tmux cannot, and that status drives waits and notifications.
• The control loop is four verbs: send-text plus Enter, read the visible screen, wait on agent-status, then act. Use send-text then a separate Enter for agent TUIs.
• The patterns that recur: three-tier orchestration with flat any-to-any messaging, fleet-wide races for hotfixes, and wait-driven runs you do not babysit.
• Worktrees keep parallel coders from colliding, and one-command relaunch makes the thousandth fleet boot trivial.
• It is early. v0.7.3, Windows in beta, and status detection that can drop an event, so build in a fallback and watch your token spend.

Sources: herdr.dev, herdr CLI reference, herdr on GitHub, tmux, Claude Code, OpenAI Codex, OpenCode, git-worktree docs.