Herdr CLI: Manage Coding Agents Without Losing Context

Running three coding agents is easy. Remembering which one needs approval, which checkout it is editing, and whether its work is actually finished is the hard part. The Herdr CLI targets that coordination problem—not the quality of the model writing your code.

For a technical lead, the useful question is not “Can I run more agents?” It is “Can I keep ownership, review, and recovery understandable as the work grows?” A faster terminal workflow is valuable only if it produces changes the team can trust.

The short answer: Herdr is an agent-aware terminal runtime. Use it to organize persistent sessions and inspect agent state. Keep Git isolation, tests, and human approval as separate controls.

This is a documentation-based walkthrough, checked against Herdr’s published 0.9 documentation and the 0.9 release announcement on September 13, 2026. The status, listing, and worktree commands were also run on a local Herdr install to confirm their output shape; the remote-machine feature was not exercised. Check your installed version before adopting anything here in automation. Sources are listed at the end.

What is Herdr, and what does it replace?

Herdr runs a background server that owns terminal sessions. Its client gives you a view of workspaces, tabs, panes, and detected coding agents. Closing the client is different from stopping the server: the documented detach workflow leaves pane processes running.

Think of the layers this way:

Herdr session
  └─ Workspace: one project or checkout
       ├─ Tab: implementation
       │    ├─ Pane: coding agent
       │    └─ Pane: test runner
       └─ Tab: review and logs

Herdr does not replace Claude Code, Codex, or another coding agent. Those programs still run in panes, use their own credentials, and make their own tool calls. Herdr adds organization, visibility, and a CLI around that work.

It also does not turn a terminal into a security sandbox. An agent with access to your shell can still reach whatever files, credentials, and network services that environment permits. A clean sidebar is not an authorization boundary. If you want a real boundary, Herdr’s agent documentation describes running the agent through a sandbox wrapper such as fence on Linux or nono on macOS, with HERDR_AGENT=<agent> set on the wrapper command so Herdr still detects the agent behind it. The restriction comes from the wrapper, not from Herdr.

If your main problem is building application workflows rather than supervising developer terminals, start with my n8n and Dify comparison. These tools operate at different layers.

1. Install Herdr and verify the version

You need a terminal, Git, a disposable repository or branch, and at least one independently installed coding agent. Authenticate that agent using its own documented setup before adding another management layer.

On a machine where Homebrew is already available, the official installation guide documents:

brew install herdr
herdr --version

The guide also covers direct installation, Nix, mise, and Windows archives. Use the instructions for your platform rather than adapting an unrelated shell command.

Keep the update mechanism consistent with installation. A Homebrew installation should be updated through Homebrew; herdr update is intended for installations managed by Herdr’s own installer. Do not switch a team to preview builds just to match a screenshot in a tutorial.

Launch a session from your repository:

cd /path/to/your/repository
herdr

Replace that path with an existing checkout. On an empty session, Herdr creates a workspace automatically. From a shell pane inside the session, inspect the runtime:

herdr status
herdr workspace list
herdr pane list

These checks establish the starting point: the server is reachable, the expected project is open, and you can identify the panes you intend to use. Fix those basics before writing a multi-agent script.

2. Separate the workspace from the checkout

A workspace is an organizational container. A Git worktree is a separate checkout. They are related, but creating more tabs does not create isolated working directories.

Two agents editing one checkout can overwrite each other’s files, mix staged changes, or make a test result difficult to attribute. I would start a team pilot with one independently scoped task per worktree and a named reviewer for each result.

Herdr’s CLI reference includes worktree creation:

# Run from a Git repository, inside the intended Herdr session.
# Use new branch names and unused destination paths.
herdr worktree create --cwd "$PWD" \
  --branch agent/api-contract \
  --path ../api-contract-review \
  --label api-contract

herdr worktree create --cwd "$PWD" \
  --branch agent/ui-validation \
  --path ../ui-validation-review \
  --label ui-validation

Each command creates a Git worktree and opens it as a Herdr workspace. The documented default does not steal focus. Inspect the workspace list and select the relevant workspace before starting its agent.

Worktrees isolate tracked file changes, not the whole runtime. Two development servers may still compete for one port. Two agents may still share a database, a cloud account, or the same .env values. Assign separate ports and test resources where the tasks require them.

Do not copy production credentials into each checkout. Give the pilot the smallest useful environment: fixtures, development accounts, and no deployment authority.

3. Start the agent, then improve detection

In the intended pane, start your already configured coding agent. For example:

claude

Herdr detects supported agents and marks each one working, blocked, or idle. Blocked detection is deliberately strict: Herdr only marks blocked when the live screen matches a known approval, question, or permission prompt, and it falls back to idle when no rule matches. A prompt shape Herdr has not learned yet can therefore show as idle for a while. herdr agent explain <target> prints the rule and the evidence behind the current state. That is useful operational information, but it is not a substitute for reading what the agent is asking you to approve.

An integration can improve the connection between Herdr and the agent. For a Claude Code setup, the documented commands are:

herdr integration install claude
herdr integration status

Review what an integration installs before using it on a shared development machine. These integrations modify agent configuration or install hooks; they are not just display preferences.

The integration documentation makes an important distinction: some integrations provide lifecycle authority, while others provide native session identity for restoration. For Claude Code and Codex, the documented integration provides session identity; state detection still uses screen manifests.

That distinction matters when a CLI changes its terminal output. A status indicator can be wrong or temporarily unknown even when the process is healthy. Treat it as a signal to inspect, not as an infallible job scheduler.

4. Inspect blocked agents before sending more work

Use the agent list to discover a target rather than assuming an identifier from an earlier session is still valid:

herdr agent list

Then substitute a target from that output:

AGENT='replace-with-a-target-from-agent-list'

herdr agent get "$AGENT"
herdr agent read "$AGENT" --source visible

For an approval prompt, --source visible returns the current screen, which is what the agent is waiting on. --source recent reads scrollback instead and defaults to the last 80 rendered rows when --lines is omitted; use it when you need the run-up to the prompt.

A blocked agent may be asking to run a command, clarify a requirement, or resolve an authentication problem. The next action depends on that reason. Automatically approving every blocked pane defeats the value of surfacing the block.

Once the target is understood and ready, a bounded prompt is easier to supervise than an open-ended instruction:

herdr agent prompt "$AGENT" \
  "Inspect the API contract. Report mismatches with the UI types. Do not edit files or run deployment commands." \
  --wait --timeout 120000

The prompt is a task instruction, not a permission mechanism. Enforce actual restrictions through the agent’s permission settings and its execution environment.

The timeout above is in milliseconds. Herdr documents that a settled wait can include blocked, not only a successfully completed task. A prompt submitted while an agent is already working can also have its wait satisfied by that active turn. Inspect the result and recent output; do not interpret a successful CLI exit as proof that your exact request passed review.

5. Verify persistence and review the result

Test detaching on a harmless task first. Herdr’s quick-start documents the default sequence as Ctrl+B, then Q. Run herdr again to reconnect.

That test verifies client detachment. Herdr’s session-state documentation separates the cases: detaching and reattaching keeps the processes running and the conversation continues because nothing stopped; a server restart does not keep processes running — the layout returns, the recent screen returns only with pane screen history, and the agent conversation resumes only with the native agent session restore integration. Session restoration and a continuously running process are different guarantees.

For the code itself, review in the relevant worktree:

cd ../api-contract-review
git status --short
git diff --check
git diff

These commands show uncommitted changes. If the agent created commits, review the branch comparison against the correct base branch too. Run the project’s actual lint, type-check, test, and build commands; do not invent a passing gate from a terminal status label.

My acceptance checklist for a pilot would be:

• Each task has an explicit scope and its own checkout.
• Each agent can be found and inspected without guessing.
• A blocked state is reviewed rather than automatically approved.
• Detaching and reconnecting preserves the expected live session.
• The final diff and project checks are reviewed before merge.

6. Local and remote machines in one client

Long-running agents do not have to live on the laptop you carry. With Herdr 0.9, the client renders the outer interface and can bring several Herdr servers into the same view. Give it the SSH target of another machine that runs Herdr, and that machine’s workspaces, tabs, and agents appear alongside your local ones. You switch machines without opening another client, and the agents keep running on their own machines when you disconnect.

Two conditions from the announcement matter for planning:

• Remote machines must be reachable over SSH — on your local network, over the internet, or through something like Tailscale. Herdr stores the SSH target and a label; it does not store passwords or private keys.
• The agent CLI still works within one server. The interface combines machines; herdr agent commands do not yet see agents running on your other machines.

So a build box, a VPS, or a Mac mini that stays awake is a reasonable home for agents that run for hours, with your laptop as the window onto them. Each machine still needs its own agent credentials and, for cloud models, its own internet access; Herdr keeps the session alive, not the model.

7. Let agents drive Herdr, carefully

Herdr ships an instruction file for agents. herdr --skill prints it, and with it an agent can list agents, open tabs, start other agents, and submit prompts through the same socket API you use by hand. That is the delegation pattern: one agent coordinates, several execute, each in its own pane.

Apply the same rules as for a human operator. A prompt is not a permission mechanism, a status label is not a review, and the delegating agent has whatever access its shell has. Give the coordinating agent a bounded task and review its output the way you would review a junior lead’s plan.

When is Herdr worth adding?

Herdr is worth evaluating when multiple agent sessions make attention management the bottleneck: you lose blocked prompts, forget which project owns a pane, or need to reconnect to ongoing work.

If one agent and a test terminal already serve you well, more orchestration may add little. Start with two bounded tasks and compare the workflow against your current terminal setup. Measure time spent finding work and reviewing it, not just the number of agents you can launch.

For an architect, the broader lesson is familiar: visible boundaries reduce coordination cost. That applies to services, teams, and automated coding sessions. My architecture walkthrough explains the same principle at the system-design level.

Key takeaways

• Herdr manages the runtime around coding agents; it does not replace them.
• Use separate worktrees for independent edits, and separate runtime resources where needed.
• Agent status helps you decide where to look; it does not certify correctness.
• Keep permissions, timeouts, and human review explicit.
• Add the tool when coordination is the problem—not simply because it is getting attention.

Once agents can call business systems, terminal organization is only the beginning. Read MCP gateway security: auth beyond the API key for the next boundary: what an authenticated agent is actually allowed to do.

Sources

• Herdr homepage — background server, agent states
• Session state and restore — what survives detach, restart, and update
• Agents and detection — strict blocked detection, sandbox wrappers, agent explain
• CLI reference — worktree, agent read sources and the 80-row default, agent prompt --wait
• Connecting the machines — multi-machine client in 0.9, SSH requirement, single-server CLI