# Herdr: A Practical Guide to Running Coding Agents

> Herdr gives coding agents persistent terminal workspaces and visible activity states. This guide covers installation, everyday controls, Git worktrees, scripted reviews, SSH, and the limits of detection and session restore.

URL: https://blog.bokvi.com/blog/herdr-guide/
Published: 2026-09-20
Tags: ai-coding-tools, ai-agents, dev-workflow

The awkward part of running several coding agents is often the waiting. One is editing a component, another is investigating a failure, and a third has been sitting at a permission prompt while you watch the wrong terminal.

[Herdr](https://herdr.dev/) brings those terminals into one place and shows which agents need attention. It keeps their own interfaces intact: prompts, command output, approval dialogs, and all. You can leave the interface, return later, and pick up the same running processes.

The useful question is how to organize that extra capacity. A screen full of agents editing the same files is still a coordination problem. This guide starts with one agent, then adds worktrees, a small automation recipe, and a few habits that make the setup easier to trust.

*Research checked September 20, 2026, against the official documentation and [Herdr v0.9.1](https://github.com/herdrdev/herdr/releases/tag/v0.9.1), the current stable release at writing. Shell examples use Bash or Zsh; agent commands assume the corresponding agent is already installed and authenticated.*

## What Herdr adds to your terminal

Herdr has four pieces worth learning:

| Piece | What to put there |
| --- | --- |
| Session | An independently running Herdr server |
| Workspace | A project or a particular checkout |
| Tab | A task layout within that workspace |
| Pane | A shell, agent, test runner, or other terminal process |

An agent occupies a pane; the pane can go back to being a shell when the agent exits. A background server owns the processes, while the client draws the interface. The official [workflow guide](https://herdr.dev/docs/how-to-work/) explains how that separation works locally and over SSH.

My suggested starting layout is deliberately small: one workspace for a repository, one pane for the agent, and one for commands you run yourself. Add a second agent when you can give it a separate question or a separate checkout. That makes it easier to tell whether more concurrency is helping.

## Get your first workspace running

On macOS or Linux with Homebrew:

```bash
brew install herdr
herdr --version
```

The project also provides a direct installer:

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

Choose one installation method. The [installation guide](https://herdr.dev/docs/install/) also covers mise, Nix, manual downloads, and native Windows. Update a Homebrew installation through Homebrew; `herdr update` is for installations managed by Herdr's own installer.

Open a project, replacing the example path with your repository:

```bash
cd ~/code/my-app
herdr
```

On an empty session, Herdr creates the first workspace for you. Run your usual coding agent in its shell, for example `claude`. Herdr detects supported agents automatically. Click panes to focus them, drag borders to resize, and use the right-click menu to split the layout. These controls are described in the [quick start](https://herdr.dev/docs/quick-start/).

The keyboard uses a prefix: press **Ctrl+B**, release it, then press the action key.

| After Ctrl+B, press… | Action |
| --- | --- |
| `v` | Split to the right |
| `-` | Split downward |
| `c` | Create a tab |
| `n` / `p` | Next / previous tab |
| `w` | Navigate workspaces |
| `Shift+N` | Create a workspace |
| `?` | Show active bindings |
| `q` | Detach the client |

Try a harmless task, detach with **Ctrl+B, q**, then run `herdr` again. Getting comfortable with leaving and returning is more useful initially than filling the screen with panes.

## Read the sidebar as an attention queue

Herdr's states tell you where to look:

| State | How to act on it |
| --- | --- |
| `working` | Let the agent continue unless you need to steer it |
| `blocked` | Inspect the recognized question or approval dialog |
| `done` | Read the newly finished response |
| `idle` | The agent is ready for input; inspect its output for context |
| `unknown` | Inspect the terminal because classification is uncertain |

`done` has a precise meaning: the agent is idle and its completion has not been marked seen. It is not a test result. The CLI and individual clients can also differ in which completions they have seen. See the [CLI state semantics](https://herdr.dev/docs/cli-reference/#agents).

That distinction changes the workflow. When an implementation finishes, review its diff and run the relevant checks. When an investigation finishes, ask whether the evidence actually establishes the cause. A green-looking sidebar should never be the reason a change gets merged.

Detection also has limits. Some integrations supply lifecycle events; others rely on matching the agent's terminal UI. A new or unusual permission screen can be classified as idle. The [agent documentation](https://herdr.dev/docs/agents/) explains these detection rules. Treat the sidebar as a useful routing aid and keep reading the actual terminal.

## Give concurrent editors separate worktrees

Two panes opened in one directory share the same files. If one agent switches branches or rewrites a module, the other sees that change immediately.

For independent editing tasks, use **one Git worktree per task**. Herdr can create the checkout and open it as a grouped workspace:

```bash
herdr worktree create \
  --cwd "$HOME/code/my-app" \
  --branch feat/search-empty-state \
  --label search-empty-state \
  --no-focus
```

Choose a fresh branch name. If the named branch already exists, Herdr tries to check it out; otherwise it creates it from `HEAD` unless you specify `--base`. The [worktree reference](https://herdr.dev/docs/cli-reference/#worktrees) documents this behavior and the checkout location.

Now give the agent a bounded assignment: “Implement the empty search state in this checkout. Follow the repository instructions, run the relevant checks, and report changed files and validation.” Keep unrelated feature work in another worktree.

A few practical boundaries still matter:

- Worktrees separate tracked file edits, but processes can still collide on ports, databases, or external services. Assign different local ports when needed.
- A reviewer in a separate checkout will not see another worktree's uncommitted changes. Commit the candidate and identify the revision to review, or provide the diff explicitly.
- Install or prepare dependencies in the new checkout before interpreting a failed command as a code defect.

For review itself, the checklist in [AI-powered code review](https://blog.bokvi.com/blog/ai-code-review/) is a useful companion: ask for concrete failures and evidence, then verify the findings.

## Automate one review before building an orchestration system

Herdr exposes layout and agent controls through its CLI. The key distinction is that `agent start` needs an existing, available shell pane. It does not create the layout for you. Creation commands return JSON IDs, so capture those IDs instead of assuming the next pane is `w1:p2`. This is the model described in [agent automation](https://herdr.dev/docs/agent-automation/).

For this example, first launch a normal Herdr session. In another Bash or Zsh terminal, with `jq` available, create a review workspace for a checkout that is no longer changing:

```bash
review_workspace=$(herdr workspace create \
  --cwd "$HOME/code/my-app" \
  --label review \
  --no-focus)
review_pane=$(printf '%s\n' "$review_workspace" |
  jq -er '.result.root_pane.pane_id')

herdr agent start code-review \
  --kind claude \
  --pane "$review_pane" \
  --timeout 60000
```

Run these steps interactively and continue only if each succeeds. The name `code-review` must be unique among live agents. If startup stops at an onboarding or trust dialog, open the pane and handle that dialog before continuing.

Once the agent is ready, submit a focused prompt and read its response:

```bash
review_prompt='Review the latest commit for correctness bugs.
Do not edit files. Report file locations, failure scenarios,
and missing verification.'

herdr agent prompt code-review "$review_prompt" \
  --wait --timeout 180000

herdr agent read code-review --source recent-unwrapped --lines 160
```

The timeout is in milliseconds. Here, three minutes is a limit on how long the CLI waits. A successful wait can also return `blocked`, so inspect the state and handle any question before treating the review as finished. If the wait times out, read the agent before retrying: the prompt may already have been delivered. For a long answer, ask the agent to write a report to a specified file and read that file; terminal history is a limited view of the result.

There is another subtlety: waits observe agent state, not a uniquely identified job. A prompt sent to an already working agent can have its wait satisfied by that earlier turn finishing. Use an available agent for a discrete review, and inspect the returned state and response before scheduling dependent work. These caveats are documented in the [automation wait behavior](https://herdr.dev/docs/agent-automation/#choose-the-control-surface).

Keep test runners in ordinary shell panes. They do not need to be registered as agents just to run a command.

## Detach, restart, and resume are different operations

Use **Ctrl+B, q** when you want to leave work running. `herdr server stop` ends the default server and its pane processes.

After a full server restart, Herdr can rebuild the saved layout, but arbitrary running commands do not survive. Eligible agent conversations can resume through their own native session support, provided a current official integration recorded the session reference. Saved terminal history is another, separate feature; replaying old output does not restart the process that produced it. The [session-state guide](https://herdr.dev/docs/session-state/) describes these recovery paths.

For an agent you use regularly, install its Herdr integration and check its status. For Claude Code:

```bash
herdr integration install claude
herdr integration status
```

The [integration guide](https://herdr.dev/docs/integrations/) lists the other supported integrations and what each installs. Initialize the agent first so its configuration directory exists, then install the integration before starting a fresh agent session. Integration roles differ: Claude Code's integration records session identity, while its visible activity state still comes from screen detection.

A sensible habit is to detach during normal work and reserve server restarts for a point when you have saved results and can restart ordinary commands.

## Keep long-running work on the machine that stays awake

A persistent session still depends on its host. If you want agents to continue while your laptop is asleep, run the workspace on an available remote machine.

The straightforward route is to SSH to that machine and launch Herdr there. Alternatively, with a configured SSH host alias such as `devbox`, use a local Herdr client:

```bash
herdr --remote devbox
```

The remote machine owns the code, agents, and processes; your local client renders the interface. Prepare the repository, development dependencies, and agent authentication on that host. The [remote access documentation](https://herdr.dev/docs/persistence-remote/) covers compatible installations, bootstrap prompts, and named remote sessions.

If connecting fails, verify `ssh devbox` first. That separates an SSH problem from a Herdr problem without changing several settings at once.

## Small adjustments that pay off

### Make notifications visible outside the active pane

On Linux and macOS, edit `~/.config/herdr/config.toml`; use `herdr --help` to confirm the resolved path. For OS notifications:

```toml
[ui.toast]
delivery = "system"
```

Merge that setting into an existing table if you already have one. Use Herdr's **reload config** menu action to reload the client and selected server settings. Notifications are suppressed for the active tab, so test with another tab selected. Terminal-delivered notifications are another option when your terminal supports them. The [configuration guide](https://herdr.dev/docs/configuration/#notifications) covers delivery choices and the macOS notification fallback.

### Diagnose a misleading status before changing detection rules

For the named agent from the review example:

```bash
herdr agent explain code-review --verbose
```

This reports the detection evidence and active manifest. It is more useful for troubleshooting than guessing from a frozen-looking spinner. Also check whether a shell startup script launched tmux *inside* the Herdr pane: Herdr cannot inspect the agents hidden behind that nested tmux process. Both behaviors are covered under [agent detection](https://herdr.dev/docs/agents/#detection-manifests).

### Name work by outcome

Prefer workspace names such as `search-empty-state` or `checkout-timeout` over `agent-2`. When several agents ask for attention, the name should tell you which decision you are about to make.

Keep assignments similarly concrete. “Investigate why this test fails and report the smallest reproduction” creates a result you can assess. “Improve the codebase” creates an open-ended stream of changes that is harder to supervise, whatever multiplexer you use.

### Leave room for verification

Keep one shell available for your own commands, and decide what evidence you need before launching each task: a reproduction, passing tests, a screenshot, or a reviewed diff. Ask the agent to report what it could not verify as well as what it completed.

Start with one real task this week. Run the agent beside a shell, detach once, return, and review the result. Add a worktree and a second assignment when you have a clear reason to run them concurrently. Herdr becomes useful when it helps you spend less time finding the right terminal and more time making the decisions the work needs.