Many Agents, One Terminal

Herdr keeps several coding agents running side by side in one terminal and tells you which one is waiting for you — what it is, a first session with Claude Code and Codex on one repository, and what its working, blocked and idle markers do and do not mean

Herdr is an open-source terminal workspace for running several AI coding agents at once. Installing it, a tested first session with Claude Code and Codex in two git worktrees, what its agent states can and cannot tell you, remote use, and when a plain terminal is enough. Last checked November 2026.

Author

Behzad Samadi

Published

November 11, 2026

Last checked 11 November 2026, on Herdr 0.9.5, with Claude Code 2.1.322 and Codex CLI 0.166.0.

You have used one coding agent. You gave it a task, watched it work, said yes to its questions, and reviewed what it did. Now you want two at once: one adding a feature while the other writes the documentation, or Claude Code and Codex trying the same thing so you can compare.

The work is not the hard part. The waiting is. Each agent stops from time to time to ask before it edits a file or runs a command, and while it waits it does nothing. With two or three agents in two or three terminal windows, you spend your time clicking between them to find the one that has been sitting on a question for ten minutes.

Herdr is a free, open-source program for exactly that. It runs in the terminal you already have, holds each agent in its own pane, and keeps a list down the side that marks every agent as working, blocked (waiting for you) or done. It also keeps the agents running when you close the window. This article covers installing it, a first session with two agents on one repository, what those markers can and cannot tell you, and when you do not need it at all. The two agents were run here, on a Mac, on a small made-up project.

It follows on from One Repository, Three Agents, which sets up git, GitHub and the agents themselves. That article is the place for installing Claude Code or Codex, and for why each agent should work in its own git worktree. This one assumes you have at least one agent working.

In short

Herdr does not replace your agents. It runs Claude Code, Codex and more than twenty others in ordinary terminal panes, and adds a sidebar that shows each one’s state.
During the task, every state was right. Both agents went working when given a task, Claude Code went blocked the moment it asked to edit a file, and Codex went done when it finished, all while the other was still waiting. One state outside the task was wrong: a freshly started Codex that had done nothing was marked done.
“Blocked” means a dialog Herdr recognises, not only a permission request. A settings menu counted as blocked too. And a dialog it does not recognise shows as idle: never take idle as permission to type.
Closing the window does not stop anything. The agents keep running in a background server; run herdr again to come back.
Give each agent its own worktree. herdr worktree create makes one and opens it as its own workspace. By default it puts them in ~/.herdr/worktrees/, not beside your project.

What it is

Herdr is two parts. A server runs in the background and owns the terminals: your shells, your agents, anything else you start. A client draws them in your terminal window. Close the client and the server carries on; open it again and everything is where you left it. This is the same arrangement as tmux or screen, which have done it for decades.

What Herdr adds is that it knows which panes hold coding agents. It looks at the program running in each pane, recognises Claude Code, Codex and the rest, and reads the bottom of the agent’s screen to decide what state it is in. The project’s own description is plain about the limits: “herdr doesn’t wrap or replace them; it owns their terminals.” Your agent runs exactly as it would anywhere else, with its own permissions, settings and sign-in.

Its words for the layout:

Workspace: one project, usually one repository. Listed in the sidebar under spaces.
Tab and pane: layouts inside a workspace, and the terminals in them.
Agent: a pane Herdr has recognised as a coding agent. Listed in the sidebar under agents, with its state.
Session: one Herdr server. Most people need one; named sessions are for keeping things completely apart.

Herdr is written in Rust, is one program with no Electron, and is under the Apache 2.0 licence. That is recent: it was released in March 2026 under AGPL-3.0, offered under AGPL or a commercial licence from 26 May, and relicensed to Apache 2.0 on 22 July 2026. Its home is herdr.dev and its code is at github.com/herdrdev/herdr. Search results also turn up forks under other names and the project’s old address; the herdrdev repository is the one to use.

Installing it

On a Mac or Linux, the project’s installer:

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

or, if you already use them, brew install herdr or mise use -g herdr. Windows has its own PowerShell line on the install page. herdr --version confirms it. herdr update updates an installer-made copy; Homebrew and mise copies are updated through those tools instead.

Then go to your project and start it:

cd my-project
herdr

The first time, a welcome box explains the mouse and the prefix key. Pressing Enter closes it, records in Herdr’s settings that you have seen it, and opens the settings at the integrations tab (per the docs). In this test the box was left open, and while it was open ctrl+b then q did nothing; no other keys were tried.

Herdr is mouse-first: click a pane to focus it, drag a border to resize, right-click for menus. On the keyboard everything starts with a prefix, ctrl+b by default, as in tmux: press ctrl+b, let go, then one key.

Action	Keys
Split right	`ctrl+b` then `v`
Split down	`ctrl+b` then `-`
New tab	`ctrl+b` then `c`
New workspace	`ctrl+b` then `shift+n`
Leave Herdr, keep everything running	`ctrl+b` then `q` (per the docs; in this test the window was closed instead)
Show every key	`ctrl+b` then `?`

One third-party guide (Bitdoze) gives a different key for leaving (ctrl+b then d) and older command names. In 0.9.5’s documentation it is q.

Optional: integrations. herdr integration install claude (or codex, and so on) lets Herdr bring an agent’s conversation back after the Herdr server itself restarts. It does this by adding a small hook to the agent’s own settings: for Claude Code, a script in ~/.claude/hooks/ and an entry in ~/.claude/settings.json; for Codex, a hook script, entries in hooks.json and [features] hooks = true in config.toml, all in ~/.codex. Codex may then greet you with a “Hooks need review” screen before its first prompt (reported in issue #5888). You do not need it for the states: for Claude Code and Codex, Herdr reads the state from the screen either way. The test below ran without any integration.

A first session: two agents, one repository

The test project was a twenty-line Python script that totals a made-up garden club’s seed swap, with two small tasks that touch different files: add a total by seed kind to the script, and write a five-line README. The set-up script is in the research folder.

One worktree per agent

Two agents editing one folder will trip over each other. Give each a git worktree, its own checkout on its own branch. Herdr can make them:

herdr workspace list        # the project's workspace id, here w1
herdr worktree create --workspace w1 --branch task-kind --label kind
herdr worktree create --workspace w1 --branch task-readme --label readme

Each appears in the sidebar as its own workspace, grouped under the repository, with a terminal already open in the new checkout. The checkouts went to ~/.herdr/worktrees/<repository>/<branch>, in your home folder, not next to the project. That is a default: --path on worktree create, or directory in the [worktrees] section of Herdr’s settings, puts them elsewhere. Remember that when you look for the files, and remove them when you are done (herdr worktree remove). You can also make the worktrees with git worktree add and open each in a workspace by hand.

Start the agents

In each worktree’s pane, start the agent as you normally would:

claude        # in the kind workspace
codex         # in the readme workspace

According to the docs, Herdr recognises an agent started this way by itself and lists it in the sidebar under agents; herdr agent rename gives it a name of your choosing. That was not tried here: the agents in this test were started with herdr agent start --kind claude (or codex), which starts a named agent from a script and waits until Herdr has recognised it.

Both agents started blocked here, and both were right to. Claude Code asked whether to trust the new folder; Codex asked the same, and on another start showed its “update available” screen. A new worktree is a new folder, so expect each agent’s trust question the first time. Not every first-run screen is recognised, though: an open report (issue #5888, 8 November 2026) lists Claude Code’s theme picker and Codex’s “Hooks need review” and new-model screens as shown idle, so a prompt sent then is typed into the screen. Look at a new agent before giving it work.

Give them work

Each got one sentence: “Do task 1 in TASKS.md… Do not touch anything else and do not commit”, and the same for task 2. Claude Code was set to ask before every edit, so that one of the two would stop and wait.

What Herdr reported, read once a second with herdr agent list (the same states the sidebar shows), against what each agent was actually doing:

Time	Claude Code	Codex	What was happening
0 s	idle	done	Both at their prompts. Codex’s done was wrong: it had just started and done nothing, and the docs say start-up does not count as completed work
+2 s	working	working	Both reading the project
+9 s	blocked	working	Claude Code showing its “Do you want to make this edit?” box, with the change
+18 s	blocked	done	Codex had written the README and stopped
+2 min 1 s	working	done	Claude Code’s edit was approved
+2 min 15 s	done	done	Claude Code had made the change and run the script to check it

Every change during the task matched the agent’s real state, to within the second. The blocked agent stayed marked blocked for the nearly two minutes it waited, while the other got on with its work and finished: the point of the tool.

In the sidebar itself, captured at the same moments, Claude Code’s marker was red while it waited and Codex’s was teal once it had finished.

Both results were right: the new function printed the right totals, the README was three lines, and each change was on its own branch with the original checkout untouched. From there it is ordinary git: review each branch and merge it, as in Three Agents.

Driving it from a script

Everything above can also be done from the command line, which is how this test was run. herdr agent list prints every agent and its state as JSON; herdr agent prompt <name> "…" --wait sends a prompt and waits until the agent is done or blocked; herdr agent read <name> prints its screen; herdr agent explain <name> says which rule produced the state. An agent can run these commands too, which is how one agent can hand work to another (herdr --skill prints the instructions Herdr gives agents for this). You do not need any of it to use Herdr, but agent explain is worth knowing when a state looks wrong.

What the states tell you, and what they don’t

Herdr uses five states. The definitions are the project’s own:

State	Means
working	The agent is busy
blocked	It needs input, approval or a decision
done	It finished and you have not looked yet
idle	It finished, or is waiting, and you have seen it
unknown	Herdr cannot tell

How it decides matters more than the list. For Claude Code and Codex (and, without an integration, most others), Herdr reads the bottom of the agent’s screen and compares it with a set of rules for that agent. It does not ask the agent. (A few, such as OpenCode, Pi, Kimi and Kilo, report their own state once their integration is installed; OMP and MastraCode need it for any state; five more report to Herdr by themselves.) So:

Blocked means “a screen Herdr recognises as a question”. It caught every dialog met here: folder trust, the update screen, the edit approval. It also marked Claude Code’s settings menu for its tools as blocked, which is not a request for permission. Read blocked as “go and look”.
A question it does not recognise shows as idle. The project says so directly: “Unusual new agent prompts may initially show as idle instead of blocked until Herdr learns that screen shape.” Open reports on the project’s issue tracker in October and November 2026 list several, for both Claude Code and Codex. None turned up in this test, but when an agent has been idle for a suspiciously long time, look at it.
Start-up can be misread too. A freshly started Codex that had not done anything was marked done in this test, though the docs say start-up does not count as completed work. A done on an agent you have just opened tells you nothing.
Idle is not permission. In the docs’ words, “idle status is not authorization to approve an action.” This matters most if you script Herdr: a script that types into an “idle” agent can type into a dialog.
Done belongs to one window. After closing Herdr and opening it again, the sidebar showed both finished agents with the plain idle marker, while herdr agent list still said done. Each open window keeps its own record of what you have looked at.
Background work is not counted. Antigravity and Grok Build show as idle once they are back at their prompt, even while their own subagents carry on.
Herdr talks to herdr.dev. It fetches new detection rules by itself, which is how a misread dialog gets fixed without a new release; the test used rules version 2026.10.11.1. It also checks for new Herdr releases. In the [update] section of Herdr’s settings, manifest_check = false stops the rule checks (at the price of fixes) and version_check = false the release checks.

None of this makes the states unreliable; during the task they were exact. They are a good way to know where to look, not a substitute for looking.

Closing the window, and coming back

Closing Herdr does not stop your agents. Here, the window was closed while both agents sat finished; herdr status still showed the server running, and both agents were still there. With nothing open, Codex was even given a new prompt from the command line and answered it. Running herdr again brought back both workspaces, both worktrees and both agents, exactly as left. The keyboard way to leave is ctrl+b then q (per the docs; in this test the window was closed instead).

A restart of the Herdr server (a reboot, or herdr server stop) is different. The layout and folders come back, but the programs that were running do not: each pane starts a fresh shell. An agent’s conversation is resumed only if its integration is installed (above), in which case Herdr starts it again with its own resume command, claude --resume <id> or codex resume <id>. That holds for a reboot too: since 0.9.4 Herdr saves before a Mac restarts so that “agents come back where they were”, but for Claude Code and Codex coming back means that resume, which needs the integration. None of this was tested here.

Running it on another machine

Agents are often happier on a machine that is always on: a desktop at home, a server, a cloud machine. Herdr has three ways to use one, described here from its documentation; this test ran on a Mac only.

SSH in and run herdr there. Everything runs on the other machine; your terminal is only a window onto it. Leave, disconnect, and SSH back later: the agents have kept working. This also works from a phone’s SSH app.
herdr --remote my-server. The agents run on the other machine, but the Herdr window is drawn by your local copy, with your own keys and theme, and you can paste images from your own clipboard. If the other machine has no Herdr, Herdr offers to install it there.
Saved machines. herdr machine add my-server keeps your own machine and several SSH machines in one window, with one combined list of agents.

All three use your ordinary SSH set-up and keys. The other machine can run Linux or macOS, or Windows on x86 (ARM64 Windows on a best-effort basis).

When a plain terminal is enough

Herdr earns its place when you have two or more agents that stop to ask you things, and you want to know which one is waiting without checking each. It helps too if you already wish your agents kept running after you close the laptop’s terminal.

You probably do not need it:

With one agent at a time. A terminal window is enough.
If you already live in tmux. tmux keeps agents running after you disconnect and has done so for years. What you would gain is the state list; what you would give up is your tmux set-up. Herdr can run inside tmux, but not the other way round: an agent inside a tmux session inside a Herdr pane is invisible to Herdr.
If your agents run unattended. An agent allowed to edit and run commands without asking rarely blocks, and the states matter less.
If you use one vendor’s own app for parallel work. Claude Code’s worktree option and Codex’s Worktree mode already put each session on its own branch (see One Repository, Three Agents). If one vendor’s agents are all you run, see whether its own app already shows you which session is waiting before adding Herdr. Herdr’s case is mixing vendors in one place, and keeping it in the terminal.

What changes

Herdr releases often. These are the facts in this article most likely to date:

Version. 0.9.5 (14 October 2026) is the newest release and the one tested. There are also frequent “preview” builds.
Agents recognised. On 11 November 2026 the documentation lists Claude Code, Codex, GitHub Copilot CLI, Cursor Agent CLI, OpenCode, Pi, OMP, Droid, Devin CLI, Kimi Code CLI, Kilo Code CLI, Hermes Agent, Qoder CLI, Qwen Code, Letta Code, MastraCode, Grok Build, xAI’s command-line app (listed there as “Grok CLI”), and Antigravity CLI, with integrations; Amp, Kiro CLI and Maki for states only; and Gemini CLI and Cline as “less tested”. Command Code, Crush, Kiro CLI, Muse Code and Prime Agent report their own state to Herdr. Any other program still runs in a pane, without a state.
A desktop app. By November 2026 herdr.dev offers a separate desktop app built on a new background program, herdr-core, and leads with it. It now calls the terminal program described here Herdr TUI, at herdr.dev/tui. The app was not tried for this article.

What changed

11 November 2026. First draft, on Herdr 0.9.5.
11 November 2026, corrected after review. A freshly started Codex was wrongly marked done; the article had said the states were right every time. Also: the state timeline was read from herdr agent list, not the sidebar; ctrl+b q and recognition of hand-started agents were not tried; worktree location is configurable; first-run screens can show as idle (issue #5888); the licence history, the release checks and the Codex integration’s changes are spelled out.

Sources

The test log, the captured screens, what was read and when, and the third-party claims that did and did not hold up are in the research folder.

The project. herdrdev/herdr: README, CHANGELOG, releases, open issues; all read 11 November 2026.
Documentation for 0.9.5, read 11 November 2026: Quick start, Install, Concepts, Agents, Integrations, Session state and restore, Persistence and remote access, How to work with Herdr, Connecting machines, Agent automation.
The site. herdr.dev, Herdr TUI, herdr-core.
On this site. One Repository, Three Agents for setting up git and the agents.