herdr cheat sheet: sessions, panes, CLI

herdr is a terminal multiplexer built for running coding agents. A background server owns your terminals, so they keep running when you close the window or lose SSH. On top of the tmux model it adds mouse control, a sidebar showing which agent panes are working, blocked or done, and a CLI that drives everything from scripts. This sheet covers the keys you press inside herdr and the CLI commands you type outside it. Every key and flag below is from the official docs at herdr.dev for version 0.9.5. herdr ships new releases often, so check herdr --version against the version above.

what it is and when to use it

The project is herdrdev/herdr on GitHub, documented at herdr.dev. Forks and npm packages that reuse the name are not covered here.

Session: a background server with its own state. Plain herdr attaches to the default session. Named sessions are fully separate.
Workspace: one project or task. It owns tabs and panes. The sidebar lists workspaces.
Tab: a layout inside a workspace.
Pane: a real terminal. It keeps running when you detach.

Reach for it when you run several long jobs or coding agents at once and want to see which one needs you. For plain shells on a server, tmux does the same job and is installed in more places.

install and check the version

These are the install routes the herdr docs list.

Command	What it does
curl -fsSL https://herdr.dev/install.sh \| sh	Linux or macOS, official install script
brew install herdr	macOS or Linux with Homebrew
mise use -g herdr	With mise
herdr --version output herdr 0.9.5	Print the installed version

Prefer not to pipe a script into sh? The docs also offer plain binaries on the GitHub releases page, named herdr-linux-x86_64, herdr-macos-aarch64 and so on. Download one, chmod +x it, and move it onto your PATH.

start, detach, and reattach

Command	What it does
herdr	Start or attach to the default session
herdr status server output status: running version: 0.9.5 endpoint_compatible: yes private_protocol: 22 private_protocol_compatible: yes socket: /home/you/.config/herdr/herdr.sock	Show whether the server is running, and its version

herdr status on its own shows the client and the server together.

prefix+q: detach. The server and every pane keep running.
Run herdr again to reattach.

Command	What it does
herdr server stop	Stop the server and every pane in it

After the server stops, the next herdr brings back the saved layout of workspaces, tabs, panes and directories. Processes don’t come back: each pane starts a fresh shell in its old directory.

named sessions

Command	What it does
herdr session attach work	Attach to a named session, creating it if needed
herdr session list output name status default running	List sessions (output trimmed to 2 of 4 columns)

The full session list output also has directory and socket columns, with each session’s directory and socket path.

Command	What it does
herdr session stop work	Stop one session
herdr session stop default	Stop the default session by name
herdr session delete work	Delete a session’s saved state

keys inside herdr

The docs suggest learning these five first:

Key	Action
`prefix+c`	New tab. herdr asks for a name. Press Enter to accept the default.
`prefix+v`	Split right.
`prefix+minus`	Split down.
`prefix+h`, `prefix+j`, `prefix+k`, `prefix+l`	Move to the pane left, down, up or right.
`prefix+w`	Workspace navigation.
`prefix+q`	Detach.

Panes:

Key	Action
`prefix+z`	Zoom the focused pane. Press again to restore.
`prefix+x`	Close the pane.
`prefix+shift+h` (and j, k, l)	Swap panes.
`prefix+r`	Resize mode.
`prefix+[`	Copy mode.

Tabs:

Key	Action
`prefix+n` and `prefix+p`	Next and previous tab.
`prefix+1` to `prefix+9`	Jump to tab 1 to 9.
`prefix+shift+t`	Rename the tab.
`prefix+shift+x`	Close it.

Workspaces:

Key	Action
`prefix+shift+n`	New workspace.
`prefix+shift+w`	Rename it.
`prefix+shift+d`	Close it.
`prefix+g`	The Goto picker. In it, `/` searches, and `b`, `w`, `i` and `d` show only blocked, working, idle or done agents.
`prefix+b`	Show or hide the sidebar.
`prefix+?`	List every active binding. Type `/` to filter.

Everything above also works with the mouse: click panes and tabs, drag split borders, and right-click for menus.

copy mode

prefix+[ enters copy mode for the focused pane. Unlike tmux, the pane keeps running and output stays live while you scroll.

Move: h, j, k, l, the word keys w, b, e, and PageUp / PageDown.
Half a page: ctrl+u and ctrl+d.
Search forward and backward: / and ?, then n and N. The search is case-insensitive unless you type a capital letter.
Start a selection: v or Space.
Copy it: y or Enter.
Leave without copying: q or Esc.
Mouse drag copies text without entering copy mode at all.

With the default prefix, ctrl+b in copy mode is the prefix, not page up. Use PageUp, or move the prefix to another key.

scripting: workspaces, tabs, panes

The CLI talks to the running server and prints JSON, so pipe it through jq. IDs look like w1 for a workspace, w1:t2 for a tab and w1:p2 for a pane.

Command	What it does
herdr workspace create --cwd ~/project --label api --no-focus	Create a workspace without switching to it
herdr workspace list	List workspaces
herdr tab list --workspace w1	List the tabs in a workspace
herdr pane list --workspace w1	List the panes in a workspace
herdr pane split w1:p1 --direction right \| jq -r .result.pane.pane_id output w1:p2	Split pane w1:p1 to the right and print the new pane’s ID
herdr tab create --workspace w1 --label logs	Add a tab named logs to workspace w1
herdr pane run w1:p2 "make test"	Run a command in a pane: types it and presses Enter
herdr pane wait-output w1:p2 --match "PASS" --timeout 60000	Wait until a line of output matches, for up to 60 seconds
herdr pane read w1:p2 --source recent --lines 20	Print the last 20 rows of a pane’s output
herdr pane send-keys w1:p2 ctrl+c	Send keys without Enter, here Ctrl+C
herdr pane rename w1:p2 tests	Label a pane
herdr pane zoom w1:p2 --toggle	Zoom a pane, or unzoom it
herdr pane close w1:p2	Close a pane and end what’s running in it

pane run sends the text and Enter together. The docs prefer it over send-text followed by send-keys enter.
wait-output waits forever if you leave out --timeout. The timeout is in milliseconds.
Inside a herdr pane, --current means "this pane", taken from the HERDR_PANE_ID variable.

agents

These commands are from the docs only. They need a supported coding agent running in a pane, which our test setup didn’t have.

Command	What it does
herdr agent list	List detected agents and their state
herdr agent wait w1:p1	Wait until an agent in pane w1:p1 is idle, done, or blocked
herdr agent read w1:p1 --source recent --lines 40	Read what an agent pane shows

The states are working, blocked (waiting for an answer), idle, done and unknown. unknown means herdr can’t tell, not that the work succeeded.

config: ~/.config/herdr/config.toml

Command	What it does
herdr --default-config	Print the fully commented default config
mkdir -p ~/.config/herdr herdr --default-config > ~/.config/herdr/config.toml	Start a config file from the defaults (this overwrites an existing config.toml)
herdr config check output config: issues found unknown config key keys.prefx; ignoring key	Check the file for mistakes
herdr server reload-config	Apply config changes without restarting panes
herdr config reset-keys	Back up the config and drop every custom keybinding

Change the prefix in the [keys] table:

~/.config/herdr/config.toml

[keys]
prefix = "ctrl+a"

Command	What it does
source <(herdr completion zsh)	Shell completion for zsh, loaded for this shell only

herdr completion also takes bash, fish, powershell and elvish.

gotchas

A misspelt key in config.toml is ignored, not fatal. herdr config check names it and exits with status 1. If a setting seems to do nothing, run the check.
Stopping the server ends every process in every pane. The layout comes back, the processes don’t. Detach with prefix+q instead.
herdr and tmux both default to ctrl+b. Run one inside the other and the outer one gets the key first, so give one of them a different prefix.
prefix+c opens a name prompt rather than creating the tab immediately.
If you installed with the install script or a downloaded binary, herdr update replaces the binary from your update channel, and herdr channel show prints stable or preview. If you installed with Homebrew or mise, update with brew upgrade herdr or mise upgrade herdr instead. Those installs don’t use the preview channel.
CLI commands act on the local server only. Picking a remote machine in the UI doesn’t redirect them. That needs the --machine prefix and a saved SSH machine, which this sheet doesn’t cover.

sources

Checked against the herdr docs for version 0.9.5 (the docs site has a version selector) and the herdr 0.9.5 Linux arm64 (aarch64) release binary. herdr releases often. On another version, run herdr --help and check the docs page for your version.

Install: https://herdr.dev/docs/install/
Keyboard: https://herdr.dev/docs/keyboard/
CLI reference: https://herdr.dev/docs/cli-reference/
Config reference: https://herdr.dev/docs/config-reference/
Session state and restore: https://herdr.dev/docs/session-state/
Repository and releases: https://github.com/herdrdev/herdr

terminal-life.com/cheatsheets/herdr/ · checked against the herdr 0.9.5 docs

herdr cheat sheet: sessions, workspaces, panes, and the CLI

//what it is and when to use it

//install and check the version

//start, detach, and reattach

//named sessions

//keys inside herdr

//copy mode

//scripting: workspaces, tabs, panes

//agents

//config: ~/.config/herdr/config.toml

//gotchas

//related on terminal-life

//sources