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 vs tmux, 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 repo:

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

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

What your agent learns

• Host readiness checks before you even try to connect
• tmux defaults — private sockets, detach-safe habits, capture over attach
• Session bootstrap for new projects (one tmux window, one agent, one job)
• The optional moshi DIR shell helper for instant session spawn
• moshi-hooks — how to emit push notifications when work finishes
• When not to use tmux at all (prefer bash background for quick, non-interactive work)

Host readiness

The most common Moshi failure mode is the host, not the client. The skill opens by validating the host:

# 1. Is mosh-server on PATH?
$ command -v mosh-server || brew install mosh

# 2. Firewall open on UDP 60000-61000?
$ sudo pfctl -sr | grep 6000   # macOS
$ sudo ufw status              # linux

# 3. Reachable over Tailscale / wireguard?
$ tailscale status

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

tmux defaults

Moshi's whole point is session resilience. That's tmux's whole point, too. The skill codifies the defaults that make them play well:

• Use a private socket (tmux -S $SOCKET) so agent sessions don't collide with your personal tmux
• Keep session names short and slug-like (claude-py, codex-fix)
• Detach-safe by default — C-b d never kills work
• Prefer capture-pane -p -J -S -200 for inspection; reserve attaching for debugging

Session bootstrap

A new agent session looks like this:

SOCKET_DIR="${TMPDIR:-/tmp}/claude-tmux-sockets"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/claude.sock"
SESSION=claude-feature

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'claude' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200

The agent knows to print monitor commands to the human immediately afterwards — attach and capture one-liners, ready to paste into Moshi.

The moshi DIR helper

Optional. A shell function that, given a project directory, creates or attaches a named tmux session in it. Drop-in for your .zshrc:

moshi() {
  local dir="${1:-$PWD}"
  local name
  name="$(basename "$dir" | tr . - )"
  cd "$dir" && tmux new -A -s "$name"
}

moshi-hooks

The notification system. Register a Stop hook on your agent that calls the Moshi webhook — pocket buzzes when Claude finishes:

# ~/.claude/settings.json
{
  "hooks": {
    "Stop": [
      { "hooks": [
        { "type": "command",
          "command": "~/.claude/hooks/moshi-notify.sh",
          "timeout": 10 }
      ]}
    ]
  }
}

When the skill activates

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

• User mentions Moshi, mosh, iOS terminal, or remote agent
• Agent detects it's in a tmux pane over a mosh connection
• Task involves a long-running job the user might want to leave and come back to
• User asks about notifications, push, or "ping me when done"

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 / Gemini / opencode?

Yes — it's a skills-format package, which most CLI agents now support. The content is agent-agnostic.

Does Moshi itself need the skill?

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