Herdr Cheat Sheet: Shortcuts, Config, Themes, and Commands

Every Herdr keybinding, CLI command, and config block you'll actually reach for — plus what each one maps to when you drive the same session from your phone with Moshi.

TL;DR: Herdr's prefix is ctrl+b (tmux-compatible). Config lives at ~/.config/herdr/config.toml — print the full defaults with herdr --default-config, reload live with herdr server reload-config. Detach with prefix+q (everything keeps running); herdr server stop is the one that actually kills your panes. Update with herdr update. And because Herdr sessions survive you leaving the desk, Moshi can pick the same workspaces up from your phone — no chords required.

Herdr is the agent-aware terminal multiplexer — sessions, workspaces, tabs, and panes, with built-in awareness of which agent panes are blocked, working, or done. We build Moshi, the iOS/Android terminal that speaks Herdr natively, so this is the reference we keep open ourselves: the shortcuts, commands, and config.toml blocks you'll reach for daily at the desk — and, where it changes the answer, what the same action looks like from a phone.

Everything here tracks the official Herdr docs — when the two disagree, trust herdr.dev (and tell us, so we can fix this page).

Keyboard shortcuts

All chords start with the prefix, ctrl+b by default — press and release the prefix, then the action key. prefix+? shows the live bindings list inside Herdr, which always reflects your own config.

Two things trip up tmux muscle memory:

• Detach is prefix+q, not prefix+d.
• Splits are prefix+v / prefix+minus, not % / ".

Every one of these is remappable — see keybindings below.

From a phone, chords are the wrong tool entirely — there's no ctrl worth reaching for on glass. When you attach to a Herdr session with Moshi, tabs become horizontal swipes, workspaces sit in a picker, and the rest of this table lives in a dedicated Herdr shortcut panel — one tap instead of a chord, same actions underneath.

CLI commands

Detach vs stop

This distinction is the whole point of a multiplexer, so it's worth being precise:

• prefix+q detaches your client. The server keeps running every pane — builds, agents, logs, all of it. Reattach later with herdr and it's exactly where you left it.
• herdr server stop ends the session. Every pane and process dies. Use it when you actually want a clean slate, not when you're just done for the day.

Close the terminal window without detaching? Same as detaching — the server is a background process and doesn't care.

The detached session is also exactly what Moshi attaches to. Detach at the desk, walk out, and the same workspaces — agents still running — appear in Moshi's connect-time picker on your phone. That round trip is the workflow the Moshi + Herdr guide walks through end-to-end.

Config: where it lives

The format is TOML. The fastest way to start is to save the defaults and edit from there:

herdr --default-config > ~/.config/herdr/config.toml

After editing, apply without restarting:

herdr server reload-config

Most UI settings apply immediately; a few startup-only options need a full restart. Set HERDR_CONFIG_PATH to point at a different file (handy for dotfile repos). The full option list is in the configuration docs.

Keybindings in config.toml

Remap anything under [keys]. The prefix itself is just another binding:

[keys]
prefix = "ctrl+b"
new_tab = "prefix+c"
next_tab = "prefix+n"
previous_tab = "prefix+p"
split_horizontal = "prefix+minus"
focus_pane_left = "prefix+h"

An action can have several bindings:

next_tab = ["prefix+n", "ctrl+alt+]"]

And you can bind arbitrary commands — this pops lazygit over the current pane:

[[keys.command]]
key = "prefix+alt+g"
type = "popup"          # also: "pane", "shell", "plugin_action"
command = "lazygit"
description = "run lazygit"
width = "80%"
height = "80%"

Command keybindings see context env vars like HERDR_ACTIVE_WORKSPACE_ID, HERDR_ACTIVE_PANE_CWD, and HERDR_SOCKET_PATH, so a bound script can act on exactly the pane you triggered it from.

If you remap heavily, one nice side effect of driving Herdr from Moshi: the shortcut panel and gestures don't care what your chords are — they call the actions directly, so your phone workflow survives any rebinding.

Themes

Herdr ships themes (Catppuccin variants among them) and can follow your system's light/dark switch:

[theme]
name = "catppuccin"
auto_switch = true
light_name = "catppuccin-latte"
dark_name = "catppuccin"

Individual colors are overridable on top of any theme:

[theme.custom]
sidebar_bg = "#181825"
active_row_bg = "#1e1e2e"
accent = "#a6e3a1"

Running the same look on both ends is a small pleasure: Moshi ships the full Catppuccin family too — Latte, Frappé, Macchiato, and Mocha — so the workspace you detach from and the phone you reattach on can match, palette for palette.

The UI, your way

A few high-leverage [ui] options:

[ui]
tab_bar_position = "bottom"          # default "top"
window_title = "{hostname}: {workspace}"
status_indicators = "symbols"        # or "dots"
tab_bar_right = [
  { type = "hostname" },
  { type = "datetime", format = "%H:%M" },
]

The sidebar's agent and workspace rows are fully composable — which tokens show (state_icon, agent, branch, git_status, …), in what order, per agent if you want:

[ui.sidebar.agents]
rows = [
  ["state_icon", "workspace", "tab"],
  ["agent"],
]

Notifications and sound are configurable per delivery channel and per agent ([ui.toast], [ui.sound]) — including turning one noisy agent off while keeping the rest.

Agent states

The sidebar rolls agent status up per workspace. The states Herdr reports:

Start claude, codex, opencode, and friends in any pane and detection is automatic.

These states are also what makes the mobile pairing more than a remote screen. With moshi-hook on the host, a blocked agent becomes a push notification on your lock screen — and because Herdr structures work into workspaces and tabs, tapping it lands you in the exact tab the agent is waiting in, approval surface ready. done rolls up the same way, so a glance at your phone answers "is anything stuck?" without attaching at all.

Updating Herdr

Preview builds: herdr channel set preview, back with herdr channel set stable.

When something's wrong

Logs live next to the config:

~/.config/herdr/herdr.log
~/.config/herdr/herdr-client.log
~/.config/herdr/herdr-server.log

HERDR_LOG=herdr=debug turns up verbosity, and herdr --help prints the resolved config path if you're not sure which file is being read. For plugin development and the socket API, see the plugins docs.

The half that doesn't fit on a cheat sheet

Everything above assumes you're at the keyboard. The other half of a Herdr setup is what happens when you're not: sessions keep running, agents keep working, and something eventually needs you. That's the half Moshi covers — your workspaces in the connect screen, blocked/working/done on your lock screen, and a tap that lands in the right tab. If you run Herdr on a desk machine and ever walk away mid-agent-run, the pairing is worth ten minutes: Moshi with Herdr →