Docs your agent reads
so you don't have to.

What it is

Moshi Skill is a skills-format package that teaches AI coding agents how to live nicely inside Moshi. It's not a library your app imports — it's a markdown-first skill your agent reads and follows.

Agents have short working memory and variable context. Instead of adding paragraphs to every prompt about mosh vs ssh, Herdr vs tmux, or hook pairing, you install the skill once; whenever an agent realizes it's operating through Moshi, it loads the skill and just behaves.

Why agent-first

The Moshi marketing site explains what the app does, for humans. The Skill explains what to do inside the app, for agents. Different readers. Different language. Different density.

• Humans want vibes, screenshots, a story. They scroll, scan, stop when something hooks.
• Agents want terse, unambiguous, executable. They read top-to-bottom, remember, and act.

Writing for both at once produces bad docs for both. Moshi Skill is the second channel — the one your agent reads silently so you don't have to.

Install

From the published repo:

$ npx skills add rjyo/moshi-skill
$ npx skills add rjyo/moshi-skill --skill moshi-best-practices
$ npx skills add rjyo/moshi-skill --list   # preview first

That's it. The skill is registered to your agent's skill directory. Next time you mention Moshi, Herdr, tmux, Easy Pair, or a long-running remote session, the agent pulls it in.

What your agent learns

• Easy Pair host setup with moshi-hook host setup (or moshi host setup)
• Host readiness checks: Mosh preferred, multiplexer on PATH, login-shell non-interactive PATH
• Herdr first for agent work — one session, workspaces per project, integrations + Herdr skill
• Why tmux stays installed: packaged moshi DIR launcher and Recent-directories one-tap still create tmux sessions
• tmux fallback defaults when Herdr isn't available or the user prefers it
• MOSHI_CLIENT for optional shell/tmux adaptations (Export ENV in Settings → Integrations → Shell)
• moshi-hook — bidirectional approvals, Live Activities, Apple Watch; required on Herdr (no screen-scrape fallback for agent prompts)
• Supported agents: Claude Code, Codex, OpenCode, Antigravity, Cursor, Kimi, Grok Build, Pi/OMP, Hermes, and more

Host readiness

The fastest setup is Easy Pair. Your agent can ask you to run one command, then scan the QR from Moshi:

$ moshi-hook host setup
# or: moshi host setup

That creates the saved connection, generates the phone-side private key, and installs Moshi's public key on the host. Anyone who scans the QR before it expires can claim access — don't share the screen or setup link.

Token pairing (moshi-hook pair --token) is separate: agent hooks, inbox, Live Activities, and Watch events — not host SSH keys.

The skill still validates the host before deeper debugging:

$ command -v herdr || true
$ command -v tmux || true
$ command -v mosh-server || true
$ herdr session list --json 2>/dev/null || true
$ tmux list-sessions 2>/dev/null || true
$ moshi-hook status   # pairing + resolved herdr/tmux binaries

An agent that knows the skill will run these checks before telling you "I can't connect." No more round-trips.

Prefer Herdr

For coding agents on Moshi 3.10+, the skill defaults to Herdr — agent state in the sidebar, workspace picker, Jump To with agent logos, Chat View, deep links, and Open Terminal landing on the event's tab. See also the tmux or Herdr? decision guide.

$ curl -fsSL https://herdr.dev/install.sh | sh
# or: brew install herdr

$ cd ~/projects/app
$ herdr

Recommended layout:

• One Herdr session on the host — Moshi surfaces workspaces for direct attach only when a single session is running
• One workspace per project, with tabs for agent / review / tests / servers
• Install Herdr integrations and the Herdr agent skill when useful

$ herdr integration install claude
$ herdr integration install codex
$ npx skills add ogulcancelik/herdr --skill herdr -g

Herdr integrations and moshi-hook install both write agent hook config and are meant to coexist. On Herdr, moshi-hook must be paired and installed — unlike tmux, there is no screen-scrape fallback for agent prompts.

tmux fallback

Keep tmux installed even on Herdr-first hosts. Use it as the primary multiplexer when Herdr isn't available, the user already lives in tmux, or they want the one-shot project launcher. The skill sets sensible defaults (history, mouse, base-index) without private sockets or inventing shell aliases.

The moshi DIR launcher

When moshi-hook is installed, moshi is a convenience alias for the same binary. Pass a directory and it creates or attaches atmux session named from the directory basename:

$ moshi .
$ moshi ~/projects/app

Outside tmux it execs tmux new-session -A. Inside tmux it creates the session detached if needed and switch-clients. Do not install the old hand-rolled moshi() shell function — that conflicts with the real binary.

moshi-hook

The agent-hooks daemon holds a WebSocket to Moshi so approvals are bidirectional — approve or deny from the Live Activity or Apple Watch, and the answer round-trips to the agent. One install covers Claude Code, Codex, OpenCode, Grok Build, Cursor, Kimi, Pi/OMP, Hermes, and more.

$ brew tap rjyo/moshi
$ brew install moshi-hook
$ moshi-hook pair --token <token from Moshi>
$ moshi-hook install
$ brew services start moshi-hook

# Linux / manual
$ curl -fsSL https://getmoshi.app/install.sh | sh
$ moshi-hook service install

Easy Pair's host setup often pairs the daemon as part of that flow; still run moshi-hook install so agent configs point at it. Verify with moshi-hook status and a short real agent task.

When the skill activates

Skills have a when_to_use / description hint. Moshi's triggers on any of:

• User mentions Moshi, mosh, Easy Pair, iOS/Android terminal, or remote agent
• Host setup / verification for SSH, Mosh, Herdr, tmux, or Zellij
• Agent detects it's in a multiplexer over a Moshi connection
• Task involves hooks, approvals, Live Activities, or "ping me when done"
• User asks for a project session, moshi DIR, or multiplexer defaults

FAQ

Do I need to read any of this?

No. That's the whole point. Install, forget, ask your agent.

Will it work with Codex / OpenCode / Grok?

Yes — it's a skills-format package, which most CLI agents now support. The content is agent-agnostic; moshi-hook install covers the common CLIs.

Herdr or tmux?

Prefer Herdr for multi-agent work on current Moshi. Keep tmux installed formoshi DIR and Recent directories. Both at once on one host is fully supported — see tmux or Herdr?.

Does Moshi itself need the skill?

No. The skill runs in the agent. Moshi is just the transport (and the pocket).