Herdr brings coding-agent sessions into one terminal

In a hypothetical review, three agent sessions are open: one has a patch, one needs permission and one is still working. Herdr puts their activity in a shared view so the supervisor can find the next useful action without hunting through terminal tabs.

Herdr is an open-source terminal multiplexer and agent runtime. It organizes several sessions in a terminal workspace and tracks agents there. That helps locate work without changing who owns the files or whether a proposed patch is right.

Several agents, one place to find waiting work

Imagine two sessions going idle. One completed checks; the other paused for permission after a partial edit. Both deserve attention, but different decisions. The status points you to the session; its diff, tests and destination state explain what it accomplished.

The project overview describes terminal workspaces, tabs and panes, a server owning sessions and a client displaying them. It supports agents including Claude Code, Codex and OpenCode and uses Apache 2.0. This is a documentation-based explanation, not a performance review.

For a runbook check, put the agent's findings beside a terminal inspecting the configuration. The shared view supplies a convenient place to follow its file references and judge the proposed corrections.

Have findings name their configuration revision and file locations. Then you can measure time saved finding the session separately from time needed to verify its answer.

How Herdr derives an agent’s status

The supervisor sees one session stop producing output. Did it finish, or is it waiting? Herdr classifies supported agents using the evidence available: some integrations send lifecycle events, while incomplete hooks leave it applying rules to foreground processes and terminal evidence. The detection documentation explains which source is authoritative for a particular agent.

That means the supervisor cannot infer the source of a status merely from seeing an integration installed. The integration roles describe Claude Code and Codex session identity for restoration while activity still uses screen detection; Pi and OpenCode can report lifecycle events. Check the agent actually running.

The automation guide defines done as idle completion not yet marked seen, not an accepted patch. unknown means uncertain classification. Read them as attention signals.

For our runbook task, the supervisor opens the completed session and finds a proposed correction. The next move is to compare its file reference with the named repository revision, not mark the patch accepted because the status changed. The permission-waiting session needs a different decision even if both panes are quiet.

Which machine is still doing the work?

With separate client and server, the viewing terminal can disconnect while the server owns running sessions. Under SSH remote access, the remote machine owns panes and sends their content to the client. That machine's identity explains what a closed laptop affects.

A remote host may keep working when the client laptop disconnects. If the laptop itself runs the work, ordinary sleep suspends it. The persistent-looking view cannot change where the process lives.

Detaching and restarting differ. A detached client can return to processes that never stopped. A restarted server restores saved layout, with other recovery dependent on optional history and supported integrations in the session-state guide. A familiar pane may contain live output, saved output or a resumed conversation; establish which.

Suppose an agent submitted a change before restart and lost its reply. Its restored conversation can show uncertainty while the destination already holds the change. Inspect that current destination before replaying and possibly duplicating the effect.

Consequential tasks need an external record of target, approval, artifact or operation ID and verification. The production-agent guide develops this. Terminal history explains what was seen; the destination establishes what exists now.

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.

Task identity outlasts a terminal pane

Suppose the supervisor automates the next runbook review. Herdr can create the workspace, start an agent in a shell pane, send the prompt and read responses. The returned identifiers tie later control to those created objects; guessing a pane number could send the next instruction to the wrong session.

Now the wait times out. Did the runbook prompt reach the agent? The supervisor needs the identity of the request being watched, not just a quiet pane. Herdr's automation contract says waits do not track individual turns, and timeout does not prove input was unsent. Check current state before sending the prompt again.

An external task ID and repository revision in the findings resolve another ambiguity after reopening. The review might be correct for yesterday’s configuration while today’s checkout has changed. Restoring its pane restores access to the review, not freshness to its conclusions.

If the patch-making session and runbook-review session share one checkout, the reviewer can see edits still in progress. Separate worktrees or another deliberate isolation method are needed for independent changes. Two panes have organized the view, not separated the files.

Grant the reviewer only its needed source and output access. A deployment command mentioned in a runbook does not require deployment authority to review. The skills guide covers enforcing that boundary through tools.

A runbook comparison as the first Herdr task

Install through the official instructions, use a disposable checkout and configured agent, and record both versions. Choose a nonproduction task with checkable output so later behavioral differences have context.

The quick start launches from a project directory. Detach with Ctrl+B, then Q; run herdr to reattach. Split a pane using its context menu for your comparison terminal.

# In your disposable project directory:
herdr

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

Ask for a comparison of runbook and checked-out configuration, findings with file references and explicit unknowns. Keep a second pane for your inspection or separate review. That tests whether the shared view helps supervision without assuming the findings are correct.

In the proposed three-session comparison, the supervisor first follows the completion signal to the findings, then the approval prompt to the session that cannot proceed. If the display cannot distinguish them, that uncertainty is part of the result. The shared view is useful only if it brings the person to the right next decision.

After a detach, the expected process should still be alive on its execution host. A full server restart asks a different question: which output and conversation state return with the saved layout, now that the original process is gone? The supervisor records that difference rather than treating a familiar arrangement of panes as proof that work continued.

Back at the completed runbook review, each file reference is checked against its named revision. Unsupported conclusions stay beside useful corrections. Time spent locating sessions and reconstructing context is counted separately from time spent reviewing findings, so faster navigation cannot conceal a poor report.

Optional history is off by default because terminal content can be sensitive. Decide whether retention fits the task before enabling it; the persistence guide describes storage and restoration. More saved context is also more material to protect.

The three sessions now leave different next steps: inspect the proposed patch, decide the requested permission, and leave the still-running work to continue. The trial’s value lies in finding those steps and recovering context, alongside useful findings and the separate restart cost. If the report is poor, more panes will not repair it; the task or evidence needs attention. Review remains proportionate to the work, from disposable exploration to shared-code and production changes.