Herdr

Herdr is an agent multiplexer: persistent named sessions, workspaces, tabs, and panes, with built-in awareness of which agent panes are blocked, working, or done. Moshi treats it as a peer to tmux and Zellij — detection on connect, the session picker, a dedicated shortcut panel, and full hook context. See Multiplexers for the support matrix.

Install

curl -fsSL https://herdr.dev/install.sh | sh

Linux and macOS. Releases are also on GitHub. Once installed, herdr update keeps it current.

Start or attach

The simplest path — start Herdr's default background server and attach:

$herdr

Named sessions are separate persistent servers, each with their own panes, tabs, and workspaces. Use them to keep work projects isolated:

$herdr session list
$herdr session attach work
$herdr session attach side-project
$herdr session stop work

When Moshi connects to a host that has running Herdr sessions, the session picker lists them under a Herdr tab. Tapping one attaches; tapping Skip drops you into a plain login shell. Moshi only shows sessions whose server is currently running — stopped sessions are filtered out the same way tmux list-sessions hides stopped servers.

Agent workflow

Inside Herdr, start your agent in a pane:

$cd ~/projects/app
$claude
$codex

The sidebar shows each agent pane's state (blocked, working, done) so you can scan the whole session at a glance. moshi-hook reads $HERDR_ENV and $HERDR_SESSION and reports kind=herdr plus the session and workspace on inbox events, so approvals and turn completion are tagged with the right session and workspace. Opening one of those agent events from the Moshi Inbox reconnects to the host and reattaches that Herdr session — useful when you have several active for different projects.

Workspaces, tabs, panes

Herdr uses a prefix-key chord model. The default prefix is Ctrl-B, matching tmux, and Moshi pre-binds the most common follow-keys in the Herdr shortcut panel:

If you've remapped the Herdr prefix in ~/.config/herdr/config, update it under Settings → Shortcuts → Herdr so the panel sends the right bytes. The setting is independent from the tmux prefix.

Shortcut panel notes

• The Herdr panel only appears when Herdr is detected on a recently connected host. Until then, the tab stays out of the picker.
• The tab quick-access row sends Ctrl-B + the tab number, the same shape as tmux window numbers. Tabs 1–9 work as-is; 10–20 depend on the prefix-chord timing and may need a custom binding in ~/.config/herdr/config.
• If you organize work by workspace rather than numbered tabs, Settings → Shortcuts → Herdr has a Hide tab selector toggle to drop the row. Workspaces (Ctrl-B w) and the goto prompt (Ctrl-B g) still cover the cases where numbered tabs run out.
• Long-press a shortcut button to edit or remove it, the same way tmux and Zellij panel shortcuts work.

Mobile-friendly tips

• Prefer separate tabs over many small panes — chord-based pane navigation is fiddly on a touchscreen.
• Use named sessions (herdr session attach <name>) to keep work projects isolated. The Moshi session picker will list them all.
• Pair Herdr with moshi-hook so approvals and turn completion reach the Moshi inbox tagged with the right session.
• The agent-state sidebar is most useful in landscape on iPad; on iPhone, fold it down with Ctrl-B chords rather than fighting for screen space.

When Herdr is not needed

For short commands and one-shot SSH work, Moshi is fine without any multiplexer. Anything long-running — agents, builds, dev servers — belongs inside one so a network drop or a backgrounded app does not kill the work. Herdr's specific edge is when you want the multiplexer itself to track agent state; if you don't need that, tmux is the more battle-tested default.

Troubleshooting

Moshi doesn't detect Herdr

The most common cause is that herdr isn't on the non-interactive SSH PATH. Moshi runs detection over a non-login, non-interactive shell, which often skips ~/.bashrc, ~/.profile, or ~/.zshrc, so the install directory (commonly ~/.local/bin or /usr/local/bin) may be missing.

Check what the SSH session actually sees:

$ssh <host> 'echo PATH=$PATH; command -v herdr'

If command -v herdr prints nothing, either symlink the binary into a directory already on PATH or extend the non-interactive PATH in ~/.ssh/environment or your shell's non-interactive rc file.

Session list is empty but Herdr is installed

Moshi calls herdr session list --json and shows only sessions whose server is running. The "default" entry that Herdr always emits is filtered out when its server is stopped. Start a session with herdr or herdr session attach <name> and reconnect.

Shortcut panel sends the wrong chord

Check that the prefix configured in Settings → Shortcuts → Herdr matches your ~/.config/herdr/config. The Herdr panel composes shortcuts as <prefix> + <suffix>, so a mismatched prefix sends bytes Herdr does not recognize and feels like the shortcut "does nothing."