Herdr: how to supervise coding agents

Supervising an agent and accepting its work are different operating decisions. Herdr can help expose which session needs attention, but its completion state cannot authorize a merge, certify a fix, or establish that a production action succeeded. Keep acceptance tied to the task and its actual destination.

Herdr addresses this small but consequential piece of operational work. It is an open-source terminal multiplexer and agent runtime: a place to keep agents running, see which need attention, and return to their terminals later. Its value for SRE teams starts with supervision. Understanding how it recognizes state, and what happens when its server stops, helps determine which work belongs there.

Use session state to choose what to inspect next, then accept the work through the repository or execution contract that owns its consequences.

For disposable local exploration, that check can be lightweight. Work that changes shared code or production state needs stronger evidence than a terminal status, regardless of how clearly the status is displayed.

What Herdr adds to agent work

Consider two hypothetical coding sessions that both become idle. One produced a patch with passing checks; the other stopped after a permission prompt and left a partial file edit. Treating both as completed work would erase the difference that matters to the reviewer. Inspect the output, task evidence, and repository state before accepting either result.

Herdr runs inside a terminal and organizes work into workspaces, tabs, and panes. A background server owns the sessions; the client displays them. The project describes support for existing coding agents, including Claude Code, Codex, and OpenCode, and publishes the runtime under Apache 2.0. This article examines documented behavior, rather than reporting a hands-on benchmark. See the Herdr project overview.

The distinction matters for anyone evaluating AIOps tools. Herdr supplies an environment for running and coordinating agents. A team still supplies the investigation, its evidence, and the standard for accepting a result. Putting a coding agent beside a log viewer does not establish that the agent can diagnose the service.

A sensible first use is work whose result can be inspected: reviewing a runbook against current configuration, proposing a regression test, or examining a deployment diff. Each produces an artifact another engineer can assess. That makes it possible to judge whether easier supervision actually improved the work.

Read the agent status correctly

Herdr identifies supported agents and classifies their activity. For agents without complete lifecycle hooks, it examines the foreground process and current terminal evidence against detection rules. Other integrations can report lifecycle events directly. The agent detection documentation describes which source has authority.

Integration installation does not mean every agent gains event-based status reporting. For example, Herdr documents the Claude Code and Codex integrations as reporting session identity for restoration; their activity state still comes from screen detection. Pi and OpenCode can use lifecycle reporting. Check the integration roles for the agent you actually run.

That creates a useful evaluation question: does the status change when your agent reaches the particular decision you care about? A permission dialog, an authentication failure, and a completed answer may all look like inactivity to someone glancing at a terminal. Test those cases separately before treating the sidebar as a dependable attention queue.

The CLI’s done state has a specific meaning: the agent is idle and its completion has not yet been marked seen. It does not certify the quality of the result. Herdr also exposes unknown when classification is uncertain. Its automation documentation explains these distinctions.

For a proposed deployment fix, acceptance might require a diff against the intended revision, a test that reproduces the original failure, and evidence that the change resolves it. Those conditions should exist before the agent begins. Otherwise, the ease of collecting completed answers can quietly become the standard for declaring work complete.

Separate a disconnect from recovery

Herdr’s server/client architecture lets a terminal client disappear while its server continues to own the work. With remote access, the remote machine owns the panes and sends terminal content to the local client over SSH. The remote access guide describes the connection paths.

Choose the execution host deliberately. A running remote host can continue while the laptop used to view it is disconnected. If execution lives on the laptop itself, ordinary machine sleep suspends that work. Moving the display and moving the computation are different operational decisions.

Herdr documents several recovery paths. Detaching retains live processes. A full server restart restores layout, but the original processes are gone. Optional screen history can restore recent output, while supported agent integrations can resume conversations. These preserve different things. See session state and restore.

The last two cases deserve care. Suppose an agent submitted a change before a restart but never received the response. Its restored conversation may contain an unresolved request. The destination may already contain the change. Recovery should begin by inspecting that destination, because repeating the request could apply it twice.

This is also why a restored terminal cannot replace a recovery record. For consequential work, retain the target, approved action, resulting artifact or operation identifier, and independent verification. Our article on agents that can write to production develops that responsibility.

Detaching and restarting preserve different things

Read diagram description

With the execution host and Herdr server still running, detaching leaves the original processes alive. A full server restart restores layout, not those processes. Optional screen history and supported conversation restoration preserve other state; verify current files and destinations before repeating an uncertain action. Diagram labels: Client detaches: Server and execution host remain running; Full server restart: Original pane processes stop; Reattach to live work: Verify the expected process continued; Restore saved layout: History and agent resume depend on configuration; Inspect current state: A restored view or conversation does not certify task success.

Coordinate agents without assuming success

Herdr exposes separate controls for terminal panes and recognized agents. A script can create a workspace, start an agent in an available shell pane, submit a prompt, and read the response. Creation commands return identifiers; scripts should capture those identifiers instead of predicting pane numbers.

However, waiting for agent state is not a transaction receipt. Herdr documents that waits do not track individual turns, and a timeout does not prove input was never sent. Read the agent before retrying. These details are part of its agent automation contract.

For an SRE workflow, assign a task identifier outside the terminal session and require the output to name it. A review artifact should also identify the repository revision it examined. If the underlying code changes, a completed review of yesterday’s revision is still yesterday’s review, however recently its terminal was opened.

Separate editing locations when agents work concurrently. Two panes aimed at the same checkout can expose each agent to changes made by the other. Use separate Git worktrees or another explicit isolation mechanism when independent edits are intended. Terminal organization alone does not establish file isolation.

Permissions need the same treatment. Start a runbook reviewer with access to the material it needs and a place to write its findings. Do not give it deployment authority simply because a deployment command exists in the runbook. The operational agent skills guide explains how to turn task boundaries into enforceable tool behavior.

Try a bounded Herdr workflow

Begin with a disposable checkout, a configured coding agent, and Herdr installed using the official installation instructions. Use a non-production task whose result you can check yourself. Record the Herdr and agent versions so an upgrade does not silently change the conditions of the trial.

The quick start uses a straightforward sequence: launch Herdr from a project directory, run the agent inside a pane, and detach with Ctrl+B followed by Q. Run herdr again to reattach. Splitting a pane from its context menu gives a second terminal for comparison.

# In your disposable project directory:
herdr

# Inside a Herdr shell pane, start your configured agent:
claude

Give the agent a task such as: “Compare this runbook with the checked-out configuration. Write findings with file references. Identify anything you cannot verify.” That request provides a concrete output while leaving room for uncertainty. A second pane can hold your own inspection or another bounded review.

Evaluate the workflow in five steps:

1. Check attention. Observe an ordinary completion and a request for approval. Confirm that the displayed state helps you find the right pane.
2. Detach during work. Reattach and verify the process and output, rather than relying on the workspace name.
3. Rehearse a restart separately. In the disposable session, record what was running, restart the Herdr server, and inspect what actually returns.
4. Review the artifact. Check its references and conclusions against the same repository revision. Record missed or unsupported findings.
5. Measure the supervision cost. Note time spent finding waiting agents and reconstructing context, alongside time spent checking their work.

Optional pane history is disabled by default because terminal output can contain sensitive material. Decide whether retained screen contents are appropriate before enabling it; Herdr’s persistence documentation describes storage and restoration behavior.

Keep Herdr if this trial makes useful work easier to supervise without obscuring its evidence. If the main delay remains reviewing unreliable answers, additional panes will not remove it. The next investment belongs in the task, its inputs, or its acceptance checks. A shorter search for the waiting agent is valuable precisely when you can make a sound decision once you find it.