Use when preparing or verifying a host for Moshi remote coding. Trigger this for Easy Pair host setup, SSH or preferably Mosh readiness, non-interactive shell PATH issues, recommending Herdr (preferred) or tmux as the agent multiplexer, creating a project session rooted at a chosen directory, adapti

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: 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: Useful macOS specific checks when relevant: Verify after changes: 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 Verify: 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): 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: 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: 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'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: 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 Capability in Moshi Herdr tmux Session / space / pane swipe + Jump To workspaces, tabs, agent aware labels windows / panes Agents inbox → Open Terminal reuses session, focuses workspace + agent tab attaches session / window Chat View / approvals / image paste full bridge via herdr CLI (hooks required) full bridge via tmux (hooks preferred; screen/title fallback exists) Agent aware TUI built in agent lifecycle + skill generic panes Packaged one shot project launcher start herdr in the project dir moshi DIR → tmux session Recent directories one tap in the app — creates a tmux session 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 Use tmux as the primary multiplexer when Herdr is unavailable or the user prefers it. Even on Herdr first hosts, leave tmux installed for the packaged launcher and Recent directories flow. Defaults Unless the user wants something different: Workflow: inspect the existing tmux config update overlapping settings instead of appending duplicates reload tmux after editing Project session ( moshi DIR ) When moshi hook is installed from Homebrew or install.sh , the packaged launcher still targets tmux : It resolves the directory and names the tmux session from the directory basename ( : in the basename becomes ). Outside tmux it exec s tmux new session A s <name c <dir (no Moshi wrapper stays alive). When already inside tmux, it creates the session detached if needed and switch client s to it instead of exec . When creating a new session manually: read the current working directory ask one concise question: should the session start from here? if the answer is no, ask for the directory default the session name to the directory basename create the session detached use the chosen directory for every initial window with tmux ... c <dir Recommended windows: 1. agent 2. review 3. tests 4. servers 5. misc Then ask the user to reconnect in Moshi. Expected result: the session is visible in the tmux selector. Enterprise Linux 10 note Some RHEL/Alma/Rocky 10 tmux 3.3a 12 through 3.3a 14 RPMs can corrupt the server on capture pane . Do not trust tmux V alone (affected builds can report next 3.4 ). Inspect the package: Moshi auto disables every capture pane feature on those builds rather than failing loudly; hook , title , and transcript based status still work. Prefer Herdr on those hosts, or install upstream tmux 3.5a+ and restart the tmux server after replacing the binary. See app hook/docs/usage.md for the full version range. 4. MOSHI CLIENT Signal MOSHI CLIENT=1 is an opt in environment variable the Moshi client exports into the remote shell so rc files, prompts, and multiplexer configs can detect a Moshi launched session and adapt. The user enables it in the app under Settings → Integrations → Shell → Export ENV (off by default; enabling requires Pro; disabling stays free). When on, it is set identically on both the Mosh path (via mosh server l MOSHI CLIENT=1 ) and the SSH fallback (via an injected export at shell start). A common use case is keeping tmux status handling predictable under Moshi. Moshi already clears status right on sessions it starts, but a custom theme that repopulates status left / status right can still fight that. Conditionally clearing them when MOSHI CLIENT is set keeps local themes intact while leaving Moshi's status handling predictable. Other uses: narrower prompts, dropping nerd font glyphs, different key bindings. Shell (in the user's rc file): tmux (in ~/.tmux.conf ): After editing, reload tmux ( tmux source file ~/.tmux.conf ). Verify, after the user toggles the setting on and reconnects from Moshi: If echo prints nothing, the toggle is off in the app — confirm with the user before editing host configs. The variable only appears in sessions opened after the toggle was flipped. 5. Agent Hooks ( moshi hook ) Moshi uses moshi hook (singular), a portable Go daemon. The daemon holds a persistent WebSocket to Moshi, so approvals are bidirectional — users can approve or deny tool calls from the iOS Live Activity or Apple Watch, and the answer round trips back to the agent. One install covers many agents. On Herdr , this section is required, not optional: interactive prompts and agent status in Moshi come only from hooks. Supported hook targets (as of current moshi hook install ): Claude Code, Codex CLI, OpenCode, Gemini CLI, Antigravity, Cursor, Kimi, Qwen Code, Grok Build, OMP (Oh My Pi), Pi, and Hermes Agent. Chat View in Moshi Pro also surfaces several of these (including Grok, Kimi, Pi/OMP, OpenCode, Codex) when hooks and transcripts are healthy. Use moshi hook / moshi , not hand written config, unless the user explicitly wants manual edits. Install via the Homebrew tap (macOS), then pair and install hooks: Linux / manual: When Easy Pair already ran host setup , the daemon is often paired as part of that flow; still run moshi hook install so agent configs point at the daemon. On macOS, moshi hook pair uses Keychain by default. If pairing over SSH fails because Keychain is locked or unavailable, prefer one of these explicit paths: For headless hosts where Keychain access is undesirable or unreliable: store file writes the host secrets to ~/.config/moshi/secrets.json with 0600 permissions and remembers the store choice for future serve , status , usage sync , and pair commands. Do not use it silently; call out that this stores secrets outside Keychain. moshi hook install is non destructive — it writes Moshi entries into the agent configs it finds (for example ~/.claude/settings.json , ~/.codex/config.toml , OpenCode plugins, Grok hooks, Pi/OMP extensions, Hermes plugins), leaving user owned hooks alone. Missing agents are skipped unless you force targets with target . It coexists with herdr integration install … when both are present. Useful companion commands: Verify: Then run a short real agent task and confirm Moshi receives a push notification or Live Activity update, and that approving from the Live Activity / Watch unblocks the agent. On a Herdr host, also confirm Agents → Open Terminal focuses the correct workspace/tab. For full CLI reference (every subcommand, flag, env var, and path), see app hook/docs/usage.md

moshi-best-practices