Lesson 01 · Using Herdr Effectively

Persistent Agent Workspaces

Run coding agents where the work lives, detach when you leave, and come back to the same live session

Your tangible win

After this lesson, you should be able to start Herdr in a project, launch one coding agent, detach without stopping it, and reattach later. You will also know what each item in the UI means.

The one-sentence model

Herdr is a background server that owns real terminal processes, plus clients that attach to render and control them. It is not a replacement for Claude Code, Codex, OpenCode, Pi, or the other agents. It gives them somewhere persistent to run.

The hierarchy

Learn the nouns in this order. Most confusion disappears once you stop treating them as synonyms.

flowchart TB S["Session"] --> W["Workspace"] --> T["Tab"] --> P["Pane"] --> A["Agent"] style S fill:#faf5ff,stroke:#9333ea,stroke-width:2px style W fill:#dbeafe,stroke:#2563eb,stroke-width:2px style T fill:#dbeafe,stroke:#2563eb,stroke-width:2px style P fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style A fill:#fef9c3,stroke:#ca8a04,stroke-width:2px

Figure 1: A session contains workspaces; workspaces contain layouts; panes contain real terminal processes; Herdr recognizes agents inside them.

Session: a persistent server namespace. The plain herdr command attaches to the default session.
Workspace: the project-level container. Use one per repo, task, or investigation.
Tab: a layout inside a workspace. Separate agents, logs, servers, or review.
Pane: a real terminal. It can run a shell, server, test, or coding agent.
Agent: a coding-agent process Herdr recognizes inside a pane.

Start where the code lives

For local work, change into the project directory and run Herdr:

cd ~/your-project
herdr

On first use, Herdr launches or attaches to the default background session. If no workspace exists, it opens one automatically. The current project should get its own workspace so the sidebar remains meaningful.

Now start the coding agent in a pane:

claude

You can substitute codex, opencode, pi, or another supported agent. Herdr detects recognized agents automatically and shows their state in the sidebar.

Important boundary

Herdr owns the terminal runtime; the agent still owns its own prompts, tools, permissions, files, and provider credentials. A Herdr pane does not make an agent's actions automatically safe.

Mouse first

You do not need to memorize shortcuts. The official quick start recommends starting with the mouse:

Click panes, tabs, workspaces, or agents to focus them.
Drag split borders to resize.
Right-click for split and tab menus.
Drag-select to copy text; double-click a token to copy it.

The minimum keyboard layer

When you want keyboard control, Herdr uses a prefix model. Press ctrl+b, release it, then press one action key:

Action	Keys
Split right	`ctrl+b`, then `v`
Split down	`ctrl+b`, then `-`
New tab	`ctrl+b`, then `c`
Workspace navigation	`ctrl+b`, then `w`
Show active bindings	`ctrl+b`, then `?`

Detach is not stop

This is Herdr's central payoff. Detach the client with:

ctrl+b q

The client disappears, but the background server keeps the panes, agents, servers, and tests running. Close the terminal window or drop an SSH connection and the same principle applies. Reattach later with:

herdr

flowchart TB C1["Attached client"] --> D["ctrl+b q"] --> S2["Background server keeps panes"] --> C2["herdr reattaches later"] style C1 fill:#dbeafe,stroke:#2563eb,stroke-width:2px style D fill:#fef9c3,stroke:#ca8a04,stroke-width:2px style S2 fill:#f0fdf4,stroke:#16a34a,stroke-width:2px style C2 fill:#dbeafe,stroke:#2563eb,stroke-width:2px

Figure 2: Detaching removes a view, not the work. To actually stop the session and its panes, use the explicit server-stop command.

To actually stop everything in the current session:

herdr server stop

Do not confuse these

ctrl+b q means “I am leaving the view.” herdr server stop means “stop the server-owned session and its panes.” Use the first for normal breaks; use the second intentionally.

Agent states are an attention queue

Herdr's sidebar is not just a process list. It helps you decide where to look:

State	Meaning
`working`	Actively running.
`blocked`	Needs input, approval, or a decision.
`done`	Finished and not yet viewed.
`idle`	Finished or waiting and already seen.
`unknown`	Herdr cannot classify it confidently.

Read blocked as an attention signal, not permission to blindly answer. Inspect the pane and decide whether the requested action is safe and in scope.

Checkpoint: create one persistent workspace

Choose a non-production project.
Run cd /path/to/project, then herdr.
Start your preferred coding agent.
Confirm it appears in the sidebar.
Detach with ctrl+b q.
Wait briefly, run herdr again, and confirm the same pane and agent are still there.

Do not run herdr server stop until you have completed the reattach check.

What keeps an agent running after you detach?

Remember this

Run Herdr where the work lives. One workspace per project. Detach to leave; reattach to return; stop the server only when you mean to stop the work.

Primary sources

This lesson follows Herdr's official Quick start, Concepts, How to work, Agents, and Agent guide. Use the one-page cheat sheet for retrieval practice.