Herdr cheat sheet: keys, commands and the agent status model

Install and start

# macOS or Linux
curl -fsSL https://herdr.dev/install.sh | sh
# or
brew install herdr

herdr            # start or reattach the default session
herdr update     # update a direct install (brew upgrade herdr for Homebrew)

Windows has a beta installer; see the install docs.

The model

Workspaces (one per project, anchored to a directory) contain tabs, which contain panes. Panes have ids like w3:p1; counters continue past 9 with letters, so w3:pH and wA:p2 are normal. A session is the server holding all of that; the client you see is just attached to it.

Keys

The prefix is Ctrl+B by default, same as tmux. Press it, release, then the key.

Text editing in Herdr's own prompts follows readline: Ctrl+A / Ctrl+E for line start and end, Ctrl+W to cut a word, Ctrl+U / Ctrl+K to cut to the start or end.

Agent status

For supported agents (Claude Code, Codex, Copilot CLI, Cursor, OpenCode, Gemini CLI, Pi, Droid, Kimi and more; the full list is in the docs), Herdr finds the agent process in a pane and reads the live bottom of its screen against detection rules. Agents with a Herdr integration report state themselves instead.

Blocked detection is strict on purpose: a prompt Herdr hasn't seen before shows as idle until a rule update covers it. Rule updates arrive from herdr.dev without a restart. Workspaces roll their panes' status up, so the sidebar tells you which project needs attention.

Install the agent integrations for native session restore and richer state: herdr integration install claude, herdr integration install codex.

CLI you'll actually use

# see what's running
herdr workspace list
herdr pane list
herdr agent list

# start an agent in an idle shell pane
herdr agent start fix-auth --kind claude --pane w3:p2

# talk to it from a script, and wait for the outcome
herdr agent prompt fix-auth "run the tests and fix failures" --wait --until blocked --until idle
herdr agent wait fix-auth --until blocked

# look at a pane without attaching
herdr pane read w3:p2

# attach straight to an agent's terminal
herdr agent attach fix-auth

# sessions
herdr session list
herdr session attach work
herdr server stop            # stops the session and everything in it

Every command has --help, and most print JSON when scripted. The CLI reference lists all of them; the socket API exposes the same operations plus an event stream (pane.agent_status_changed and friends) for tools that want to react instead of poll.

Remote access

• From another computer: ssh host then herdr, or herdr --remote user@host to attach from your local Herdr with your own keybindings. Saved machines: herdr machine add.
• From a phone: an SSH app plus the keys above, or an app that uses Herdr's API to give you a native pane list and notifications. That's what Melta does; Moshi also supports Herdr.
• Notifications: a plugin can run a command on pane.agent_status_changed. Melta's plugin posts blocked and done events to send a push.

Configuration

Config lives in ~/.config/herdr/. The prefix key, keybindings, themes and update behaviour are documented in the configuration reference. If you change the prefix, set the same one in your phone app so its prefix button matches.

Sources

• Herdr docs: Keyboard
• Herdr docs: Agents
• Herdr docs: CLI reference
• Herdr docs: Persistence and remote access