Moshi Best Practices

interface:
  display_name: "Moshi Best Practices"
  short_description: "Prepare or verify a host for Moshi."
  default_prompt: "Use $moshi-best-practices to prepare or verify a host for Moshi, configure tmux, create a tmux project session with the packaged `moshi DIR` launcher, and set up moshi-hook."


---
name: moshi-best-practices
description: 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, tmux defaults, creating a tmux project session rooted at a chosen directory, adapting shell or tmux behavior with the `MOSHI_CLIENT` env signal, installing Moshi agent hooks for Claude Code or Codex CLI, or using the packaged `moshi DIR` tmux launcher.
metadata:
  updatedAt: "2026-05-13"
---

# 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

## 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 provide `moshi` as a symlink to `moshi-hook`.

## 1. Host Readiness

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

```bash
moshi-hook 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 tmux; fallback is SSH plus tmux
- the host has a working SSH entry point
- `tmux` is installed
- `mosh-server` is installed when the user wants Mosh, otherwise SSH plus tmux is acceptable
- both resolve in the current shell and in the login shell's non-interactive mode
- at least one tmux session exists so the Moshi selector can appear.

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

Useful checks:

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

Useful macOS-specific checks when relevant:

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

Verify after changes:

```bash
command -v tmux
tmux list-sessions
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server' || true
```

Then ask the user to reconnect from Moshi. Expected result: the tmux selector appears, and the transport can use Mosh instead of plain SSH when configured.

## 2. tmux Environment

Use these defaults unless the user wants something different:

```tmux
set -g history-limit 100000
set -g mouse on
set -g set-titles on
set -g set-titles-string "#I: #W"
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
```

Workflow:

- inspect the existing tmux config
- update overlapping settings instead of appending duplicates
- reload tmux after editing

## 3. MOSHI_CLIENT Signal

`MOSHI_CLIENT=1` is an opt-in environment variable the Moshi iOS client exports
into the remote shell so rc files, prompts, and tmux configs can detect a
Moshi-launched session and adapt. The user enables it in the app under
**Settings → Integrations → Export ENV** (off by default). 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).

The main use case is protecting Moshi's swipe-to-change-window gesture, which
reli