Moshi with Herdr

Herdr calls itself "to coding agents what tmux is to terminals" — a multiplexer that doesn't just keep processes alive, but knows which agent panes are blocked, working, or done. Moshi treats it as a first-class peer to tmux and Zellij, and then goes further: because Herdr structures work into workspaces and tabs, Moshi can put your workspaces in the connect-time picker, follow you as you move between them, and route an agent's approval straight back to the exact tab it came from.

That's the pairing this guide is about: an agent-aware multiplexer on the host, an agent-aware terminal in your pocket, speaking the same language about where everything is.

What you'll learn

• How Herdr's session → workspace → tab → pane model maps onto agent work
• Attach from Moshi's picker at the workspace level, not just the session level
• Lay out one workspace per project, with agents whose state rolls up to the sidebar
• Drive tabs and workspaces with the Herdr shortcut panel, swipes, pinch, and taps
• Follow agent events from the lock screen to the exact workspace and tab
• Keep several Moshi sessions parked on different workspaces without them fighting

The shape of a herd

Herdr organizes work in four levels, and the names matter because Moshi surfaces all of them:

• A session is a persistent background server — your shells and agents live in it, and it survives any disconnect, exactly like a tmux server. Most people run one; named sessions (herdr session attach work) keep bigger setups isolated.
• A workspace groups the tabs for one project or initiative, usually anchored to a directory. The sidebar rolls each workspace up to its most urgent agent state, so a glance tells you which project needs you.
• Tabs and panes are the familiar multiplexer primitives — real PTYs, so your shell, prompt, and tools are untouched.

The agent awareness is the differentiator: an agent pane carries a semantic state — blocked, working, done, idle — not just a window name. Claude Code, Codex, OpenCode, Cursor, and friends are recognized out of the box.

Install and first attach

On the host:

$curl -fsSL https://herdr.dev/install.sh | sh
$herdr
# starts the default background session and attaches

Linux and macOS are stable; herdr update keeps it current. Once it's running, every Moshi connect to that host detects it — Herdr sessions get their own tab in the session picker, alongside any tmux or Zellij sessions on the same machine.

Pick a workspace, not just a session

Here's where the Moshi integration starts paying for the extra structure. With tmux, the picker offers sessions and you find the right window after attaching. With Herdr, when you're running a single session — which is most people — the picker skips the redundant session level and lists your workspaces directly:

• The workspace Herdr currently has focused carries a focused dot.
• A workspace you already have open in another Moshi tab shows an Active badge, so you resume that tab instead of opening a duplicate.
• Tap a workspace and Moshi focuses it before attaching — you land looking at the project you picked, not whatever was focused last.

Running several named sessions? The picker lists them with their default/running state, labeled session ‧ workspace so nothing collides.

One workspace per project

The layout that works is the obvious one: a workspace per project (or per initiative), a tab per agent or task inside it. Herdr's CLI makes the scaffolding scriptable:

$herdr workspace create --cwd ~/projects/api --label api
$herdr workspace create --cwd ~/projects/web --label web

Then start agents in their tabs as usual:

$claude
# next tab: codex, a dev server, a shell…

The sidebar now earns its pixels: each workspace rolls up to its most urgent agent state, so "api is blocked, web is still working" is readable before you've switched anywhere. On an iPhone the sidebar costs real estate — fold it away and lean on Moshi's inbox for the same information; on an iPad in landscape, keep it open and you have a mission-control view inside the terminal itself.

Driving Herdr from a phone

The shortcut panel

Herdr uses a prefix-chord model with Ctrl-B as the default prefix — deliberately tmux-compatible. Moshi ships a Herdr panel with the common follow-keys pre-bound:

A tab quick-access row sends Ctrl-B + the tab number for tabs 1–9, the same shape as tmux window numbers. Note the one habit to retrain coming from tmux: detach is q, not d.

If you've remapped the prefix in ~/.config/herdr/config, set the same key under Settings → Shortcuts → Herdr — it's independent of your tmux prefix, so a Ctrl-A tmux habit and a stock Ctrl-B Herdr coexist fine. Long-press any panel button to edit or remove it.

Gestures over chords

The faster paths skip the prefix entirely:

• Swipe left or right in the terminal to move between tabs — Moshi sends the right chord for whichever multiplexer it detects, Herdr included.
• Pinch out to zoom a pane full-screen, pinch back to restore the layout. tmux and Herdr both bind zoom to prefix + z, and the gesture sends the matching one.
• Tap. Herdr's layout is mouse-aware — tabs, panes, and menus are clickable — and Moshi passes touch through, so a tap lands where a click would.

Events that know their workspace

Pair Herdr with moshi-hook and the integration gets its best trick. The daemon reads Herdr's environment, so every approval, question, and turn-completion arrives in Moshi's inbox tagged kind=herdr plus the session, workspace, and tab it came from — the event detail screen shows all three.

That context is actionable, not decorative:

• Open terminal on an agent event reconnects to the host, attaches the right Herdr session, and focuses the exact workspace and tab the agent is waiting in. With four projects live, "answer the blocked agent" is one tap with zero navigation.
• Approve and Deny resolve from the lock screen, watch, or Dynamic Island without opening the app at all — same as every agent setup, see the Claude Code guide for that full loop.

And when you bounce between several Moshi sessions parked on different workspaces of the same herd, Moshi re-focuses each one's workspace as you return to it — Herdr's focus is shared server-side state, and Moshi quietly puts it back where that session expects to be.

Mobile habits that work

• Tabs over panes. Chord-driven pane hopping is fiddly on glass; a phone screen fits one pane well. Save splits for an agent-plus-logs pair you'll zoom between.
• Label workspaces after the project. The label is what you'll see in the picker, on the session card, and on inbox events — api beats workspace 2 three times over.
• One named session is usually enough. Reach for extra named sessions when you want hard isolation (work vs. side projects); otherwise the single-session workspace picker is the smoothest path.
• Let the inbox be your sidebar. On iPhone, Moshi's Needs you / Working / Done kanban shows the same agent states the Herdr sidebar tracks — keep the sidebar folded and the inbox open.

Troubleshooting

Moshi doesn't detect Herdr

Detection runs over a non-interactive SSH shell that often skips your rc files, so herdr in ~/.local/bin may be off PATH. Check with ssh <host> 'command -v herdr' and symlink or extend the non-interactive PATH if it prints nothing — the Herdr doc has the full steps.

The session list is empty

Moshi lists only sessions whose server is running — Herdr's always-present "default" entry is filtered out when stopped, mirroring how tmux hides stopped servers. Start one with herdr and reconnect.

Panel buttons or swipes do nothing

Almost always a prefix mismatch: Settings → Shortcuts → Herdr must match ~/.config/herdr/config. The panel composes every shortcut as prefix + suffix, so a wrong prefix sends bytes Herdr ignores.

Where to go next

• tmux or Herdr? — which workspace fits your work
• Running a fleet of agents — the multi-agent patterns Herdr was built for
• Moshi with tmux — the battle-tested default, if you go the other way
• Herdr and Multiplexers — reference docs and the support matrix