On this page5 sections
You return to three coding-agent sessions. One has a patch to show you. One stopped at a permission question. The third is still working. Before you can help any of them, you have to remember which terminal contains which conversation.
Herdr's terminal interface brings those sessions into one place, with tabs, panes and indications of which agents need attention. In this hypothetical review, that means less hunting for the waiting agent and more time looking at what it actually needs: a code review, a permission decision or simply room to finish.
This guide concerns the open-source Herdr terminal multiplexer and agent runtime: software that holds several terminal sessions together and manages agents running inside them. The project homepage now leads with a native app; the terminal version, Herdr TUI, is the subject here. It uses Apache 2.0 licensing and supports agents including Claude Code, Codex and OpenCode. The explanation is based on documentation, not an installation or performance test.
Bring the runbook and its reviewer together
Give one of our agents a small job: compare a runbook with the configuration in a disposable checkout, a local copy of a project's files. Put another terminal beside it so you can inspect the referenced files. Herdr supplies the shared workspace; the agent supplies proposed findings.
Now two sessions go quiet. One finished its checks. The other made a partial edit and stopped to ask permission. Their silence looks similar from a distance, but opening the right one leads to a very different next step.
The useful saving is the time spent finding and reconstructing the work. It does not automatically shorten the review itself. Ask the runbook agent to name the configuration revision and exact file locations. Then you can follow a finding to the lines it describes, rather than wonder whether the agent and you are looking at the same version.
How does Herdr know an agent is waiting?
Some agents tell Herdr when they start working, stop or need an answer. For others, Herdr has to look: it identifies the process in the pane and applies detection rules to the live terminal screen. The agent-detection documentation explains those two routes. A status is only as definite as the information available to classify it.
An installed integration does not necessarily supply both kinds of information. The integration guide distinguishes a reference used to resume an agent's conversation from reports of its current activity. Claude Code and Codex integrations provide session identity for restoration while activity still comes from screen detection. Pi and OpenCode can report their activity directly. Check the agent you are actually running rather than infer behavior from the presence of an integration.
In the automation interface, done means idle completion that has not yet been marked seen. It does not mean the patch passed review. unknown means Herdr cannot confidently classify the agent. These labels help you decide where to look.
For the runbook comparison, looking means opening the findings and checking their file references against the named revision. The other quiet session may still need permission to proceed. Herdr can bring that question to your attention without deciding its answer for you.
Close the view, not the machine doing the work
Herdr separates the client you watch from the server that owns the sessions. With remote access over SSH, an encrypted connection to another machine, the remote host runs the panes and sends their contents to your client. Losing the viewing connection need not stop those processes.
That distinction is pleasantly practical when the work lives on a remote host: disconnect the laptop, and the host can keep working. But if the laptop itself runs the processes, putting it to sleep ordinarily suspends them. A persistent terminal cannot lend an asleep computer an awake processor.
A restart is different again. Detach the client while the server and execution host stay running, and you can return to the same processes. Stop and restart the server, and the original processes are gone. The session-state guide describes how saved layout returns and how optional screen history or supported agent restoration can recover other parts of the experience.
| What you see again | What that lets you check |
|---|---|
| A session after detaching | Whether the expected process kept running on the intended host. |
| The layout after a server restart | Which commands ended and which need a new start. |
| A resumed agent conversation | Whether its account still matches the files and external destination. |
| Saved terminal output | When the displayed result happened, rather than assume it is current. |
Imagine our patch-making agent submitted a change just before a restart, then lost the reply. Its conversation may say it is unsure; the destination may already contain the change. Inspect the destination before asking it to repeat the submission. Restoring the conversation restores its uncertainty too.
For work with consequences outside the terminal, keep the target, approval, artifact or operation ID, and verification in the task's own record. The production-agent guide explains that operating arrangement. The terminal helps reconstruct what the agent saw; the destination tells you what happened to the thing it changed.
Read both restoration paths
The detach path assumes the Herdr server and execution host stay running. Reattaching lets you check that the expected process continued. In the full-server-restart path, original pane processes stop and the saved layout returns. Screen history and agent conversation restoration depend on configuration and support. In either case, current files and destinations establish the task's result; a familiar view alone does not.
Which request is this quiet pane answering?
You can also arrange the runbook review through automation. Herdr can create a workspace, start an agent in an available shell pane, send a prompt and read the response. Keep the identifiers those creation operations return. They identify the objects you created; a guessed pane number might send the next instruction to a different session.
Suppose the wait for the review times out. It is tempting to send the prompt again, just to be sure. But the documented wait behavior does not track individual conversation turns, and a timeout does not establish that the prompt was never sent. First inspect the current session and its task. Otherwise the second request may duplicate work already underway.
A task ID and repository revision in the findings help with another quiet ambiguity. Yesterday's review can still be a good review of yesterday's files. Reopening its pane today does not make those findings current.
Nor do two panes make two independent copies of the files. If the patch-making agent and the runbook reviewer share a checkout, the reviewer may read an edit halfway through. Separate worktrees, which give the work separate checked-out files, or another deliberate isolation method are needed when the changes must be independent.
The reviewer also needs only the source and output access its task requires. Reading a deployment command in a runbook is not a reason to grant permission to deploy. The skills guide develops how tools can enforce that distinction.
Try it on a runbook you can check
For a proposed first trial, follow the official terminal installation instructions, prepare a disposable checkout and configure the agent you intend to use. Record both versions. Choose nonproduction work with findings you can check, so a later change in behavior has something definite to be compared with.
The quick start begins in a project directory. These commands launch Herdr and then the configured agent inside one of its shell panes:
# In your disposable project directory:
herdr
# Inside a Herdr shell pane, start your configured agent:
claude
Use a pane's context menu to split out a comparison terminal. Ask the agent to compare the runbook with the checked-out configuration, giving file references and stating what it cannot establish. Keep the second pane for your inspection or a separate review. The shared view should make that back-and-forth easier to follow.
In our three-session trial, follow a completion signal to the findings and an approval prompt to the session that needs a decision. If the display cannot distinguish them, record that uncertainty. Then detach with Ctrl+B, followed by Q, and run herdr to reattach. Check whether the expected process continued on its execution host.
A full server restart is a separate part of the proposed trial, not another name for detaching. Establish which output and conversation state return once the original process has gone. Compare the restored findings with their named file revision, keeping useful corrections and unsupported conclusions distinguishable. Measure time spent locating sessions and reconstructing context separately from time spent reviewing the findings.
There is a privacy choice here as well. Optional screen history is off by default because terminal output can contain sensitive material. The persistence guide explains its storage and restoration. Saving more context can make reopening work easier, but it also leaves more material to protect; choose retention for the task rather than enable it just because it is available.
The trial has done its job if you can find each session's next useful step without losing track of what the work achieved. Disposable exploration can need a lighter review than a change to shared code or production. In either case, quicker navigation is a different benefit from better findings, and restart recovery has its own cost.
Back at the three panes, the choices are now less mysterious: inspect the patch, answer the permission question, and let the working agent continue. If the runbook report itself is poor, improve the task or its source material. Herdr has helped you find the conversation that needs attention; the next useful contribution still happens inside it.
Sources & context
Sources linked in this article. Read alongside the author’s analysis; a citation does not independently verify a publisher’s claims.
- Herdr project overviewherdr.dev
- agent detection documentationherdr.dev
- integration rolesherdr.dev
- automation documentationherdr.dev
- remote access guideherdr.dev
- session state and restoreherdr.dev
- official installation instructionsherdr.dev
- quick startherdr.dev
