moshi-best-practices

Moshi のベストプラクティス

このスキルを使用すると、あらゆるホストを Moshi から使いやすくできます。

次のいずれかに使用してください：

• 新規セットアップ
• 既存セットアップの検証

Moshi は Herdr、tmux、Zellij をファーストクラスのマルチプレクサーとして扱います。Herdr のサポートは iOS 3.1 で導入されました。以下のワークフロー機能は 3.10 以降を前提としています。エージェント作業には Herdr を推奨します。Jump To、Chat View、Agents 受信トレイ、ディープリンク、2 本指でのセッション/スペース/ペインのスワイプ、Open Terminal は、いずれも Herdr のワークスペースとエージェントタブでよりスムーズに動作します。Herdr 優先のホストであっても、tmux はインストールしたままにしてください — パッケージ化された moshi DIR ランチャーと Moshi の最近のディレクトリのワンタップフローは、依然として tmux セッションを作成します。Zellij は、ユーザーがすでに使用している場合にサポートされます。

ルール

• 編集する前に調査します。
• プラットフォーム固有のセットアップスクリプトよりも、直接の設定編集を優先します。
• 変更した後は、すべての結果を検証します。
• 旧式の moshi シェルヘルパーやエイリアスをインストールしないでください。現在のインストールでは、同じバイナリが moshi として公開されています（moshi-hook の便利なエイリアスです）。
• コーディングエージェントのセッションには、tmux よりも Herdr を優先します。それでも tmux はインストールしたままにしてください。moshi DIR ランチャーと Moshi の最近のディレクトリのワンタップセッションは、どちらも tmux を作成します。Herdr をインストールできない場合、またはユーザーがすでに tmux を常用していてそこに留まりたい場合は、tmux のみをデフォルトにします。
• Herdr ホストでは、moshi-hook をペアリングし、moshi-hook install を実行しておく必要があります。tmux とは異なり、Herdr にはエージェントプロンプト用の画面スクレイピングのフォールバックがありません — フックが唯一のプロンプトソースです。

1. ホストの準備状況

Moshi の SSH/Mosh の新規セットアップでは、moshi-hook が利用可能な場合は Easy Pair を推奨します：

moshi-hook host setup
# or: moshi host setup

Moshi から Easy Pair の QR をスキャンするようユーザーに伝えてください。これにより、保存されたホスト接続が作成され、スマートフォン側の秘密鍵が生成され、Moshi の公開鍵がホストにインストールされます。セキュリティ境界について明確に伝えてください：有効期限が切れる前に QR をスキャンした人は誰でも、そのホストへの SSH アクセスを取得できます。したがって、画面やセットアップリンクを共有すべきではありません。

Easy Pair と moshi-hook pair --token を混同しないでください。トークンペアリングは、エージェントフック、受信トレイ、Live Activities、Apple Watch イベント専用です。

目標とする結果：

• 優先トランスポートは Mosh とマルチプレクサーの組み合わせです。フォールバックは SSH（または Pro が利用可能な場合は Eternal Terminal）とマルチプレクサーの組み合わせです
• ホストに機能する SSH エントリポイントがある
• Herdr がインストールされている（推奨）かつ、ランチャー/最近のプロジェクトのフローのために tmux がインストールされたままである。Zellij がすでにある場合は問題ありません
• ユーザーが Mosh を希望する場合は mosh-server がインストールされている
• バイナリが現在のシェルおよびログインシェルの非対話モードで解決される
• Moshi のセッションセレクターが表示されるように、少なくとも 1 つのマルチプレクサーセッションが存在する
• 選択したマルチプレクサーが Herdr の場合、moshi-hook がペアリングされ、フックがインストールされている

少数の実際のチェックで調査します。OS 固有の仕組みは最小限に抑えますが、検証は省略しないでください。

便利なチェック：

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'

必要に応じた macOS 固有の便利なチェック：

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

変更後の検証：

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

その後、Moshi から再接続するようユーザーに依頼します。期待される結果：マルチプレクサーセレクターが表示され（Herdr のセッション/ワークスペースおよび/または tmux セッション）、設定されている場合はトランスポートにプレーンな SSH ではなく Mosh を使用できます。

2. マルチプレクサー：Herdr を推奨

Herdr はエージェントファーストのターミナルマルチプレクサーです。Moshi はこれをファーストクラスでサポートしています（セッションカード、ワークスペースチューザー、タブ上のエージェントロゴ付き Jump To、Chat View、ディープリンク、タブ/スペース/ペインを切り替えるスワイプ、一番下までスクロール、マウスモード、開いている Herdr セッションを再利用する Agents 受信トレイ、イベントの Herdr タブに着地する Open Terminal）。

前提条件： Moshi における Herdr のエージェント機能は、moshi-hook がペアリングされ、moshi-hook install が実行されていることに依存します。tmux とは異なり、Herdr にはエージェントプロンプト用の画面スクレイピングのフォールバックがありません — フックによるキャプチャが唯一のプロンプトソースです。

インストール

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

確認:

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

デーモンは herdr を PATH に加えて Nix プロファイルディレクトリ、~/.local/bin、/opt/homebrew/bin、/usr/local/bin から解決します。非標準のインストール (Nix、カスタムプレフィックス) の場合のみオーバーライドを設定してください:

# 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

moshi-hook status で確認します — その人間向け出力は、デーモンが解決できる tmux、Zellij、Herdr のバイナリを報告します (--json はこの診断を省略します)。

プロジェクトセッションを開始する

作業が行われる場所で Herdr を起動します:

cd ~/projects/app
herdr

コーディングエージェント向けの推奨レイアウト (固定のウィンドウ名ではなく、ワークスペース / タブ):

1. ホスト上に 1 つの Herdr セッション を維持し、プロジェクトごとに 1 つのワークスペース を置きます — Moshi が直接アタッチ用のワークスペースを表示するのは、単一の Herdr セッションが実行されている場合のみです
2. プライマリエージェント、レビュー、テスト、サーバー、その他のためのタブ
3. Herdr にペイン内のエージェントを検出させます。役立つ場合は対応するインテグレーションをインストールします:

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

名前付きセッションを使用するのは、ホストが genuinely 複数を必要とする場合のみです (その場合 Moshi はワークスペース選択の代わりにセッション一覧を表示します):

herdr --session app

Herdr 自身のインテグレーションと moshi-hook install はどちらもエージェントフック設定を書き込みます (たとえば ~/.claude/settings.json へ)。これらは非破壊的で、共存することを意図しています — Herdr を Moshi と併用する場合は両方を実行してください。

人間側のセットアップが完了したら、セッション内のエージェントがペインを操作できるように Herdr エージェントスキルを提供します:

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

Herdr のデフォルトでデタッチします (Ctrl+b q、再マップされていない場合。Moshi は Opt/Alt 修飾キーを含む設定可能な Herdr プレフィックスも公開しています)。herdr または herdr --session <name> で再アタッチします。

次に、ユーザーに Moshi で再接続するよう依頼します。期待される結果: Herdr セッションがセレクターに表示されます。ホストに単一のセッションがある場合、Moshi は直接アタッチ用のワークスペースを表示できます。

Moshi エージェントにとって tmux より Herdr が優れている理由

Moshi の機能	Herdr	tmux
セッション / スペース / ペインのスワイプ + Jump To	ワークスペース、タブ、エージェント対応ラベル	ウィンドウ / ペイン
エージェント受信トレイ → Open Terminal	セッションを再利用し、ワークスペース + エージェントタブにフォーカス	セッション / ウィンドウにアタッチ
チャットビュー / 承認 / 画像貼り付け	herdr CLI 経由の完全なブリッジ (フックが必要)	tmux 経由の完全なブリッジ (フック推奨。画面 / タイトルのフォールバックあり)
エージェント対応 TUI	組み込みのエージェントライフサイクル + スキル	汎用ペイン
パッケージ化されたワンショットプロジェクトランチャー	プロジェクトディレクトリで herdr を起動	moshi DIR → tmux セッション
アプリ内の最近のディレクトリのワンタップ	—	tmux セッションを作成

デフォルトの推奨: Herdr をインストールしてユーザーのエージェント作業をそこに置き、かつ tmux もインストールしたままにする ことで、moshi DIR ランチャーと最近のディレクトリのワンタップセッションを利用できるようにします。

3. tmux フォールバック

Herdr が利用できない場合、またはユーザーがそれを好む場合は、tmux を主要なマルチプレクサーとして使用します。Herdr 優先のホストであっても、パッケージ化されたランチャーと最近のディレクトリのフローのために 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

ワークフロー:

• 既存の tmux 設定を確認する
• 重複を追加するのではなく、重複する設定を更新する
• 編集後に tmux をリロードする

プロジェクトセッション（moshi DIR）

moshi-hook を Homebrew または install.sh からインストールした場合、パッケージに含まれるランチャーは依然として tmux を対象としています：

moshi .
moshi ~/projects/app

これはディレクトリを解決し、ディレクトリのベース名から tmux セッション名を付けます（ベース名内の : は _ になります）。tmux の外では tmux new-session -A -s <name> -c <dir> を exec します（Moshi のラッパーは動作し続けません）。すでに tmux 内にいる場合は、必要に応じてセッションをデタッチ状態で作成し、exec する代わりにそのセッションへ switch-client します。

手動で新しいセッションを作成する場合：

• 現在の作業ディレクトリを読み取ります
• 簡潔な質問を 1 つ行います：このディレクトリからセッションを開始しますか？
• 答えが「いいえ」の場合は、ディレクトリを尋ねます
• セッション名はデフォルトでディレクトリのベース名にします
• セッションをデタッチ状態で作成します
• すべての初期ウィンドウで、選択したディレクトリを tmux ... -c <dir> とともに使用します

推奨ウィンドウ：

1. agent
2. review
3. tests
4. servers
5. misc

次に、ユーザーに Moshi で再接続するよう依頼します。期待される結果：セッションが tmux セレクターに表示されます。

Enterprise Linux 10 に関する注意

一部の RHEL/Alma/Rocky 10 の tmux-3.3a-12 から 3.3a-14 の RPM は、capture-pane でサーバーを破損する可能性があります。tmux -V だけを信頼しないでください（影響を受けるビルドは next-3.4 と報告することがあります）。パッケージを確認してください：

rpm -q tmux

Moshi は、それらのビルドでは大きなエラーを出して失敗する代わりに、すべての capture-pane 機能を自動的に無効化します。フック、タイトル、トランスクリプトに基づくステータスは引き続き機能します。それらのホストでは Herdr を優先するか、上流の tmux 3.5a 以降をインストールし、バイナリを置き換えた後に tmux サーバーを再起動してください。完全なバージョン範囲については app-hook/docs/usage.md を参照してください。

4. MOSHI_CLIENT シグナル

MOSHI_CLIENT=1 は、Moshi クライアントがリモートシェルにエクスポートするオプトインの環境変数で、rc ファイル、プロンプト、マルチプレクサー設定が Moshi 起動のセッションを検出して適応できるようにします。ユーザーはアプリの Settings → Integrations → Shell → Export ENV で有効化します（デフォルトではオフ。有効化には Pro が必要。無効化は無料のまま）。オンの場合、Mosh 経路（mosh-server -l MOSHI_CLIENT=1 経由）と SSH フォールバック（シェル起動時に注入される export 経由）の両方で同一に設定されます。

一般的なユースケースは、Moshi 配下での tmux ステータス処理を予測可能に保つことです。Moshi は自身が起動するセッションで status-right をすでにクリアしますが、status-left / status-right を再設定するカスタムテーマはそれと競合する可能性があります。MOSHI_CLIENT が設定されている場合に条件付きでこれらをクリアすることで、ローカルテーマをそのまま維持しつつ、Moshi のステータス処理を予測可能に保てます。その他の用途：より狭いプロンプト、nerd-font グリフの削除、異なるキーバインド。

シェル（ユーザーの rc ファイル内）：

if [ -n "$MOSHI_CLIENT" ]; then
  # running under Moshi — trim prompts, skip heavy glyphs, etc.
fi

tmux（~/.tmux.conf 内）：

# propagate the variable into tmux sessions attached by this shell
set-option -ga update-environment " MOSHI_CLIENT"

# keep status regions clean for Moshi clients when a theme would repopulate them
if-shell '[ -n "$MOSHI_CLIENT" ]' {
  set -g status-left ''
  set -g status-right ''
}

編集後は、tmux をリロードします（tmux source-file ~/.tmux.conf）。

ユーザーが設定をオンに切り替えて Moshi から再接続した後に確認します：

echo "$MOSHI_CLIENT"                       # expect: 1
tmux show-environment | grep MOSHI_CLIENT  # expect a value in new sessions (tmux only)

echo が何も出力しない場合、アプリ内でトグルがオフになっています。ホスト設定を編集する前にユーザーに確認してください。この変数は、トグルが切り替えられた後に開かれたセッションにのみ現れます。

5. エージェントフック (moshi-hook)

Moshi は moshi-hook (単数形) を使用します。これはポータブルな Go デーモンです。このデーモンは Moshi への永続的な WebSocket を保持するため、承認は双方向になります — ユーザーは iOS の Live Activity や Apple Watch からツール呼び出しを承認または拒否でき、その回答はエージェントへと往復します。1 回のインストールで多くのエージェントをカバーできます。

Herdr では、このセクションは任意ではなく必須です。Moshi における対話型プロンプトとエージェントのステータスは、フックからのみ取得されます。

サポートされているフック対象 (現在の moshi-hook install 時点): Claude Code、Codex CLI、OpenCode、Gemini CLI、Antigravity、Cursor、Kimi、Qwen Code、Grok Build、OMP (Oh My Pi)、Pi、および Hermes Agent。Moshi Pro の Chat View でも、フックとトランスクリプトが正常であれば、これらのいくつか (Grok、Kimi、Pi/OMP、OpenCode、Codex を含む) が表示されます。

ユーザーが明示的に手動編集を望まない限り、手書きの設定ではなく moshi-hook / moshi を使用してください。

Homebrew タップ (macOS) 経由でインストールし、その後ペアリングとフックのインストールを行います:

brew tap rjyo/moshi
brew install moshi-hook
moshi-hook pair --token <YOUR_TOKEN>   # token comes from the Moshi mobile app
moshi-hook install                     # writes hook configs for installed agents
brew services start moshi-hook         # keeps the daemon alive across reboots

Linux / 手動:

curl -fsSL https://getmoshi.app/install.sh | sh
moshi-hook pair --token <YOUR_TOKEN>
moshi-hook install
moshi-hook service install             # systemd user unit

Easy Pair がすでに host setup を実行している場合、デーモンはそのフローの一部としてペアリングされていることがよくあります。それでも、エージェント設定がデーモンを指すように moshi-hook install を実行してください。

macOS では、moshi-hook pair はデフォルトで Keychain を使用します。Keychain がロックされている、または利用できないために SSH 経由のペアリングが失敗する場合は、次の明示的なパスのいずれかを優先してください:

security unlock-keychain ~/Library/Keychains/login.keychain-db
moshi-hook pair --token <YOUR_TOKEN>

Keychain へのアクセスが望ましくない、または信頼できないヘッドレスホストの場合:

moshi-hook pair --token <YOUR_TOKEN> --store file

--store file はホストのシークレットを 0600 パーミッションで ~/.config/moshi/secrets.json に書き込み、将来の serve、status、usage --sync、pair コマンドのためにストアの選択を記憶します。これを無言で使用しないでください。これはシークレットを Keychain の外に保存することを明示してください。

moshi-hook install は非破壊的です — 検出したエージェント設定 (たとえば ~/.claude/settings.json、~/.codex/config.toml、OpenCode プラグイン、Grok フック、Pi/OMP 拡張機能、Hermes プラグイン) に Moshi のエントリを書き込み、ユーザー所有のフックはそのままにします。存在しないエージェントは、--target で対象を強制しない限りスキップされます。両方が存在する場合、herdr integration install … と共存します。

便利な関連コマンド:

moshi-hook status              # pairing, socket, WS, resolved tmux/zellij/herdr binaries
moshi-hook logs -f             # tail the daemon log
moshi-hook usage --sync        # push Claude / Codex / OpenCode / Kimi / Grok usage
moshi diff .                   # local git diff viewer (host gateway)
moshi-hook servers             # discover local web servers for in-app browser / serve-sim

確認:

moshi-hook status
moshi-hook logs -f

その後、短い実際のエージェントタスクを実行し、Moshi がプッシュ通知または Live Activity の更新を受信すること、および Live Activity / Watch からの承認がエージェントのブロックを解除することを確認してください。Herdr ホストでは、Agents → Open Terminal が正しいワークスペース/タブにフォーカスすることも確認してください。

完全な CLI リファレンス (すべてのサブコマンド、フラグ、環境変数、パス) については、モノレポの app-hook/docs/usage.md、または rjyo/homebrew-moshi タップにあるミラーされたドキュメントを参照してください。

6. 簡単な検証チェックリスト

セットアップ後、ホストは次の条件を満たしている必要があります:

1. Easy Pair または SSH キーが機能し、Moshi からの再接続が成功する
2. mosh-server が存在する場合は Mosh が優先される
3. Herdr (推奨)、tmux、または Zellij がログイン非対話シェルの PATH にある — Herdr が主要であっても tmux はインストールしたままにする
4. セレクター用に、少なくとも 1 つの Herdr セッション/ワークスペース、tmux セッション、または Zellij セッションが存在する
5. moshi-hook status がペアリング済み + 接続済みを示す; 使用中のエージェントにフックがインストールされている (Herdr が選択したマルチプレクサーの場合は必須)
6. 任意: MOSHI_HERDR_PATH は、デーモンが解決できない非標準の Herdr インストール場所にのみ使用する
7. 任意: MOSHI_CLIENT は、ユーザーが Export ENV (Pro) を有効にし、rc/tmux の適応が必要な場合にのみ使用する