Moshi Best Practices

Moshi Best Practices

Use this skill to make any host feel easy to use from Moshi.

Use it for either:

• fresh setup
• verification of an existing setup

Moshi treats Herdr, tmux, and Zellij as first-class multiplexers. Herdr support landed in iOS 3.1; the workflow features below assume 3.10 or later. Prefer Herdr for agent work: Jump To, Chat View, Agents inbox, deep links, two-finger session/space/pane swipes, and Open Terminal all land more cleanly on Herdr workspaces and agent tabs. Keep tmux installed even on Herdr-first hosts — the packaged moshi DIR launcher and Moshi's Recent-directories one-tap flow still create tmux sessions. Zellij is supported when the user already runs it.

Rules

• Inspect before editing.
• Prefer direct config edits over platform-specific setup scripts.
• Verify every outcome after changing it.
• Do not install the old moshi shell helper or alias. Current installs expose the same binary as moshi (a convenience alias for moshi-hook).
• Prefer Herdr over tmux for coding-agent sessions. Still keep tmux installed: both the moshi DIR launcher and Moshi's Recent-directories one-tap sessions create tmux. Default to tmux-only when Herdr cannot be installed or the user already lives in tmux and wants to stay there.
• On Herdr hosts, moshi-hook must be paired and moshi-hook install must have run. Unlike tmux, Herdr has no screen-scrape fallback for agent prompts — hooks are the only prompt source.

1. Host Readiness

For a fresh Moshi SSH/Mosh setup, prefer Easy Pair when moshi-hook is available:

moshi-hook host setup
# or: moshi host setup

Tell the user to scan the Easy Pair QR from Moshi. This creates the saved host connection, generates the phone-side private key, and installs Moshi's public key on the host. Call out the security boundary: anyone who scans the QR before it expires can claim SSH access to the host, so they should not share the screen or setup link.

Do not confuse Easy Pair with moshi-hook pair --token; token pairing is only for agent hooks, inbox, Live Activities, and Apple Watch events.

Target outcome:

• preferred transport is Mosh plus a multiplexer; fallback is SSH (or Eternal Terminal where Pro is available) plus a multiplexer
• the host has a working SSH entry point
• Herdr is installed (preferred) and tmux stays installed for launcher / recent-project flows; Zellij is fine if already present
• mosh-server is installed when the user wants Mosh
• binaries resolve in the current shell and in the login shell's non-interactive mode
• at least one multiplexer session exists so the Moshi session selector can appear
• when Herdr is the chosen multiplexer, moshi-hook is paired and hooks are installed

Inspect with a small set of real checks. Keep OS-specific mechanics minimal, but do not skip verification.

Useful checks:

command -v herdr || true
command -v tmux || true
command -v zellij || true
command -v mosh-server || true
herdr session list --json 2>/dev/null || true
tmux list-sessions 2>/dev/null || true
LOGIN_SHELL="${SHELL:-/bin/sh}"
"$LOGIN_SHELL" -c 'command -v herdr'
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server'

Useful macOS-specific checks when relevant:

dscl . -read "/Users/$USER" UserShell
systemsetup -getremotelogin || true

Verify after changes:

command -v herdr || command -v tmux
herdr session list --json 2>/dev/null || tmux list-sessions
"$LOGIN_SHELL" -c 'command -v herdr || command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server' || true
moshi-hook status || true   # human output reports resolved tmux/zellij/herdr binaries; keep stderr

Then ask the user to reconnect from Moshi. Expected result: the multiplexer selector appears (Herdr sessions/workspaces and/or tmux sessions), and the transport can use Mosh instead of plain SSH when configured.

2. Multiplexer: Prefer Herdr

Herdr is an agent-first terminal multiplexer. Moshi has first-class support for it (session cards, workspace chooser, Jump To with agent logos on tabs, Chat View, deep links, swipe-to-switch tabs/spaces/panes, scroll-to-bottom, mouse mode, Agents inbox reuse of an open Herdr session, and Open Terminal landing on the event's Herdr tab).

Prerequisite: Herdr's agent features in Moshi depend on moshi-hook being paired and moshi-hook install having run. Unlike tmux, there is no screen-scraping fallback for agent prompts on Herdr — hook capture is the only prompt source.

Install

curl -fsSL https://herdr.dev/install.sh | sh
# or: brew install herdr
# or: mise use -g herdr

Verify:

command -v herdr
herdr --version
"$LOGIN_SHELL" -c 'command -v herdr'

The daemon resolves herdr from PATH plus Nix profile dirs, ~/.local/bin, /opt/homebrew/bin, and /usr/local/bin. Only set an override for non-standard installs (Nix, custom prefix):

# Linux: put it in the systemd user unit
systemctl --user edit moshi-hook    # Environment=MOSHI_HERDR_PATH=/path/to/herdr
systemctl --user restart moshi-hook.service

# macOS: add MOSHI_HERDR_PATH to the brew services plist, then
brew services restart moshi-hook

Confirm with moshi-hook status — its human output reports the tmux, Zellij, and Herdr binaries the daemon can resolve (--json omits this diagnostic).

Start a project session

Start Herdr where the work lives:

cd ~/projects/app
herdr

Recommended layout for coding agents (workspaces / tabs, not fixed window names):

1. keep one Herdr session on the host, with one workspace per project — Moshi surfaces workspaces for direct attach only when a single Herdr session is running
2. tabs for the primary agent, review, tests, servers, and misc
3. let Herdr detect agents in panes; install matching integrations when useful:

herdr integration install claude
herdr integration install codex
# herdr integration install --help  # full target list
# herdr integration status

Use a named session only when the host genuinely needs more than one (Moshi then shows a session list instead of the workspace chooser):

herdr --session app

Herdr's own integrations and moshi-hook install both write agent hook config (for example into ~/.claude/settings.json). They are non-destructive and are meant to coexist — run both when using Herdr with Moshi.

After the human is set up, offer the Herdr agent skill so in-session agents can drive panes:

npx skills add ogulcancelik/herdr --skill herdr -g

Detach with Herdr's default (Ctrl+b q unless remapped; Moshi also exposes a configurable Herdr prefix, including an Opt/Alt modifier). Reattach with herdr or herdr --session <name>.

Then ask the user to reconnect in Moshi. Expected result: the Herdr session appears in the selector; if the host has a single session, Moshi can surface workspaces for direct attach.

Why Herdr over tmux for Moshi agents

Default recommendation: install Herdr and put the user's agent work there, and keep tmux installed for the moshi DIR launcher and Recent-directories one-tap sessions.

3. tmux Fallback