Herdr is a terminal workspace manager for AI coding agents. A background server owns the real terminals, so your agents keep working after you detach — and it reads each pane to tell you which agent is working, blocked, or done. This guide teaches the concept model, then makes you practise the keys until they stick.
Like tmux, it is a multiplexer: a background server holds real terminal processes and clients attach to render them. Panes survive detach, a closed terminal, and a dropped SSH connection. Unlike tmux, it is mouse-first and agent-aware.
The terminals live in a background server, not in your terminal window. Close the lid; the work continues.
Panes, tabs, workspaces, split borders and right-click menus are all clickable. Keybindings are optional.
Herdr detects coding agents inside panes and surfaces each one's state so you never hunt for the stuck one.
A CLI and a local socket API let scripts — and agents themselves — control Herdr programmatically.
.tmux.conf advice. The model is familiar; the surface is its own.macOS & Linux. Windows PowerShell: irm https://herdr.dev/install.ps1 | iex — and if endpoint security blocks that fileless command, use the install.cmd route from the docs. Check with herdr --version; update with herdr update.
This is the order the docs teach them in, smallest scope last. Click any rung to expand it.
herdr attaches to the default session. Named sessions (herdr session attach work) are fully separate runtime namespaces — most people only ever need the default.agents, logs, server.working, blocked, done, idle, unknown. Shown live in the sidebar.blocked is the state that earns its keep — it means an agent stopped and needs an answer from you, so you don't go pane by pane looking for whoever is waiting.
Straight from the walkthrough. Tick them off as you go — progress is saved locally.
HERDR_ENV=1 is set you're attached already — skip step 1. Herdr blocks nested launches by design, so never run herdr from inside a pane.Detaching leaves everything running — that's the whole point. To actually stop the server and its panes:
A multiplexer sits between your terminal and the programs inside it — and those programs already claim most key combinations. If Herdr grabbed common keys directly it would break them. So it reserves one: press ctrl+b, release, then press an action key. prefix+? lists every active binding live.
| Action | Key |
|---|---|
| New tab | prefix c |
| Split right / down | prefix v / prefix - |
| Move between panes | prefix h j k l |
| Workspace navigation | prefix w |
| Detach, leave everything running | prefix q |
These cover most daily movement. Everything else can stay on the mouse.
zoom z · close x · swap shift+h/j/k/l · resize mode r · copy mode [
next/prev n/p · jump 1–9 · rename shift+t · close shift+x
new shift+n · rename shift+w · close shift+d · goto picker g · sidebar b
A drill for the real keymap. You get a task; press the actual chord. The pane view reacts so you can see what each binding does, not just memorise it. Two-step bindings work exactly like Herdr: arm the prefix, then press the action key.
Press Start to begin.
Herdr works with no config at all. When you want one: ~/.config/herdr/config.toml on Linux/macOS, %APPDATA%\herdr\config.toml on Windows.
Sections: [keys] bindings · [theme] themes · [ui] sidebar & UI · [terminal] shell defaults · [update] channel.
| Symptom | First move |
|---|---|
| Agent not detected, or wrong state | herdr agent list |
| Want to know why it classified a pane | herdr agent explain <target> --json |
| Integration behaviour unclear | herdr integration status |
| Runtime / socket looks off | herdr status, status server, status client |
| A keybinding does nothing | Outer terminal or DE owns the chord — rebind either side |
~/.config/herdr/ (Linux/macOS) or %APPDATA%\herdr\ (Windows). Named sessions live under sessions/<name>/ inside that directory.herdr integration install claude adds native session restore, while Claude's state still comes from screen detection. Check the support table before assuming.SSH to the machine and run herdr there — works like tmux.
herdr --remote <host> attaches as a local client. Trade-offs are in the how-to-work doc.
Herdr ships a skill file that teaches a coding agent to control Herdr from inside a pane — splitting panes, running commands without stealing focus, reading output, and waiting until another agent is genuinely blocked.
For agents with no skill system, add the SKILL.md from the repo to their global custom instructions instead. For scripting, the CLI reference and socket API docs are the surface to read.
Help me understand and set up Herdr. Read https://herdr.dev/agent-guide.md first, then walk me through it step by step.