ガイド

iPhone から Claude Code を動かす

このアプリが存在する理由そのもののウォークスルーです。手順は 4 つ。ホストに接続し、 herdr を入れ、Claude Code を起動し、ロック画面の通知から該当ペインへ飛んで権限プロンプトに応答します。 ここに載せている文言とコマンドは、すべて実際のアプリと実行内容そのままです。

1 ホストに接続する
SSH の接続情報を入力して初回のみホストキーの指紋を確認し、 その接続のマルチプレクサに herdr を選びます。
2 エージェントを起動する
herdr ペインで claude と打つか、Moshpit に新しい git worktree を作らせてその中で Claude Code を起動します。
3 iPhone を置いて待つ
Claude Code が許可を求めるとロック画面に通知が届き、 タップするだけで質問しているペインが開きます。

始める前に必要なもの。 SSH で到達できるサーバー、iOS 18 以降の iPhone、 そしてサーバーにインストール済みの Claude Code です。Moshpit は Claude Code のインストールを行わず、 Anthropic の API とも直接通信しません。シェルを操作するだけで、Claude Code はその中で動くプログラムのひとつです。

herdr は必須ではありません。 エージェントの状態を推測ではなく確かなデータとして扱うため、 このガイドでは herdr を使います。tmux を使う経路も用意しており、 tmux コントロールモード と プッシュ通知とライブアクティビティ で詳しく解説しています。

ステップ 1

ホストに接続できるようにする

入力項目は 4 つと、指紋の確認が 1 回だけ。ノート PC からすでに ssh できるサーバーなら、1 分で終わります。

接続を追加する

ホーム右上の + をタップします。フォームは次のように分かれています:

  • 接続 — 名前、ホスト、ポート (デフォルトは 22)、ユーザー名。名前とホストを入力すると 保存 が有効になります。
  • 認証 — パスワード または SSH キー。 設定 → SSH キー で作成した鍵を選ぶか、フォームへ直接 PEM を貼り付けられます。
  • 詳細設定 — マルチプレクサ を herdr に設定します。 バイナリが特殊な場所にある場合を除き、カスタムパス欄は空のままで構いません(カスタムパスを指定するとそのまま信頼され、機能プローブをスキップします)。

マルチプレクサは全体設定ではなく接続ごとに選びます。ホストごとにインストール済みのツールは異なるため、 グローバル既定値にすると「なぜこのホストだけ繋がらないのか」という混乱の原因になるからです。

初回のみ指紋を確認する

初回接続時にはハンドシェイクが一時停止し、サーバーから提示されたホストキーが表示されます:

New Host

First connection to your-host:22.

Key fingerprint:
SHA256:…

Verify it matches the server (e.g. `ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`).

          [ Cancel ]   [ Trust ]

Moshpit があなたの代わりに指紋を検証することはできないため、照合用コマンドを表示しています。 保存済みの鍵が後から変わった場合、ダイアログは ⚠️ ホストキーが変更されました に変わり、 新旧 2 つの指紋を並べたうえで、既定ボタンが 切断、破壊的操作として 新しいキーを信頼 が表示されます。

先に知っておきたい制限。 信頼済みホストキーの一覧表示や削除画面はありません。 接続を削除しても指紋の記憶は消えず、信頼情報は端末ごとに保存されバックアップには含まれないため、 新しい iPhone ではホストごとに再確認されます。正当な再生成のあとに更新するには、⚠️ ダイアログで承認するのがアプリ内での唯一の方法です。

また、接続フォームへ直接入力したパスワードと PEM には Face ID 保護が付きません。 読み取りのたびに確認が入るのは、キーを追加 で Face ID を要求 をオンにして作成した鍵だけです。 パスフレーズ付きの暗号化秘密鍵はそのままでは使えません。

ステップ 2

ホストに herdr を入れる

herdr は CLI コーディングエージェント向けに書かれた単一の Rust バイナリです。 各ペインのプロトコルフィールドとして agent_status を返すため、Moshpit はホスト側へ何も追加せずに Claude Code が待機中であることを把握できます。

インストール

# macOS / Linuxbrew
brew install herdr

# everything else
curl -fsSL https://herdr.dev/install.sh | sh

apt-get のコマンドはありません。herdr はどの Linux ディストリビューションのリポジトリにも収録されていないためです。 存在しない sudo apt-get install -y herdr を案内して「unable to locate package」で失敗させるようなことはしません。

インストーラはバイナリを ~/.local/bin に配置し、rc ファイルは意図的に書き換えません。 Moshpit はプローブや herdr 起動時の PATH にこのディレクトリを含めるため、ホスト側で PATH を変更しなくても動作します。

見つからない場合はそのまま知らせる

herdr が入っていないホストに herdr 指定で接続すると、エラーで落とすのではなく閉じられるバナーを表示します:

  • バナー:「このホストに herdr が見つかりません — プレーンシェルセッションです。」と herdr をインストール ボタン。
  • インストール支援シートが開き、適切なコマンドと「Moshpit が黙ってインストールすることはありません。 以下のコマンドをシェルで実行してください — sudo とその出力はすべて表示されます。」という説明が表示されます。
  • ターミナルで実行 を押すと開いているシェルへコマンドが貼り付けられ、sudo のプロンプトや出力をすべて確認できます。 隣には コマンドをコピー と 再チェック があります。
  • セッション自体はそのまま使えます。プレーンシェルが開き、黙って tmux に切り替えることは決してありません。 tmux と herdr は別々のセッションを持つため、無断で切り替えると別作業の画面を見せてしまうからです。

対象とした herdr のバージョン。 統合実装は herdr main / v0.8.0(protocol 19) を基準に設計し、 実機検証は当時の brew install herdr で入った 0.7.3(protocol 16) で行っています。 スナップショットデコーダはフィールド欠損があっても全体失敗にせず、その項目だけ穏やかにフォールバックします。

0.7.3 で見える違いとして、ペインのコマンド名が返らないため、ターミナルのパンくずリスト第 3 セグメントは 実行中プログラム名ではなく pane N と表示されます。ただしペイン選択シートへの入口として残してあります。

このガイドでは Mosh ではなく SSH を使ってください。 Mosh は描画済みの画面差分を送るため行フレーミングが失われ、 herdr のフレームプロトコルを運べません(tmux -CC が通らないのと同じ理由です)。 Mosh 上では herdr 自身の全画面 TUI が動き、iPhone では幅の約 3 分の 1 を herdr のサイドバーに取られます。 なおコントロールシートは別の SSH サイドカー経由で動作します。

ステップ 3

Claude Code を起動する

方法は 2 つあります。すでにあるペインで起動するか、Moshpit に隔離された git worktree を切らせて起動するか。 iPhone から使うなら後者が特におすすめです。

既存のペインで起動

新しく覚えることはなし

  • herdr ペインで claude と入力するだけ
  • herdr がペインの画面内容から自動認識
  • 設定不要ですぐ使える

新規エージェントタスク

worktree、ワークスペース、エージェントを一括作成

  • ホームの AGENTS 見出しから 1 シートで実行
  • ホスト上に新しい git worktree を切り、その中で Claude Code を起動
  • メインの作業ツリーには一切触れない
  • herdr 専用(tmux には同等の機能なし)

どちらの方法でも、herdr は画面内容からエージェントを推定します。推定ではなくエージェント自身に状態を通知させたい場合は、 ホスト上で一度 herdr integration install claude を実行してください。より確実になりますが必須ではありません。 このガイドの内容はすべて未実行のまま動作します。

シートの各項目

グループ タスク(フッター:「ホスト上に git worktree を作成し、その中でエージェントを起動します。作業ツリーは変更されません。」)

  • リポジトリ — メニュー選択。Moshpit は開いている全ペインの cwd を git rev-parse --show-toplevel で解決すると同時に、$HOME 配下を更新日時順でスキャンします。 検索中は「リポジトリを検索中…」、見つからない場合は「見つかりません」と表示されます。 末尾には常に その他… があり、リポジトリのパス を手入力できます。
  • ブランチ — ホストへ送る前に iPhone 上で検証します。空文字、スペース、先頭の - や /、 末尾の /、..、末尾の .lock、および ~ ^ : ? * [ \ を含む名前は分かりやすいメッセージで弾かれ、不正な値がホストへ届くことはありません。
  • エージェント — herdr server agent-manifests --json から読み込みます。 既定値は claude、次に codex、それ以外は先頭のものを優先します。

グループ 最初のメッセージ(フッター:「任意。エージェント起動後に送信します。自分で入力する場合は空欄のままにしてください。」)。 大きなチェックアウトには数十秒かかることがあるため、実行中は 開始 ボタンが 開始中… に変わります。

「開始」で実際に実行されるコマンド

SSH 経由で 3 つのコマンドを順に実行します。隠れた処理はなく、入力した文字列はすべてシングルクォートで安全にエスケープされます。

herdr worktree create --cwd '~/code/payments-api' --branch 'fix-webhook-retry' \
     --label 'fix-webhook-retry' --focus --json
→ {"type":"worktree_created",
    "workspace":{"workspace_id":"w4"},
    "root_pane":{"pane_id":"w4:p1",
                 "cwd":"~/.herdr/worktrees/payments-api/fix-webhook-retry"}}

herdr pane run 'w4:p1' 'claude'          <- コマンドを入力して Return を送信

herdr agent send 'w4:p1' '<first message>'   <- 2 秒後、入力がある場合のみ送信

新しい git worktree、新しいワークスペース、そのチェックアウト先にいるフォーカス済みペインが用意されます。 2 段階目に agent start ではなく pane run を使うのは、 agent start --workspace が worktree のディレクトリを引き継がないためです。 pane run なら自分で打つのとまったく同じ手順が目に見える形で実行されます。

最初に目にする画面

実機検証では、cwd が ~/.herdr/worktrees/…/fix-scroll-jump のワークスペースが作られ、 git worktree list でブランチ作成が確認でき、Claude Code が起動してディレクトリ信頼プロンプトで停止しました。 herdr がそのペインを agent: claude / status: blocked とマークすると、 ホームのエージェント欄は即座に AGENTS 1 · 要対応 に変わります。この最初のプロンプトに答えるのがステップ 4 です。

終わったあとの片付け

ホームのワークスペース行を長押し → ワークツリーを削除。 この項目は実際にリンクされた worktree であるワークスペースにだけ表示されます。最初の実行に --force は付きません:

  • 「…」のワークツリーを削除しますか? — 「~/.herdr/worktrees 配下のブランチチェックアウトを削除します。 payments-api 本体は変更されません。」
  • 未コミットの変更があって herdr が拒否した場合にだけ、2 つ目の確認ダイアログが出ます: 「…」に未コミットの変更があります — 「これらの変更は他には残っていません。ワークツリーを削除すると失われます。」 ボタンは それでも削除 / 残す。ここで明示的に選んだときだけ --force が付きます。

このステップの制限事項。

worktree はリポジトリの隣ではなく ~/.herdr/worktrees/<repo>/<branch> に作られます。 パス変更オプションはこのバージョンにはありません。大きなリポジトリではチェックアウトに数十秒かかります。

エージェントの起動フラグは自動選択されません。 マニフェスト既定の claude コマンドがそのまま実行されます。 --dangerously-skip-permissions のようなオプションが必要な場合は、ペイン上で直接入力してください。

herdr が見えるのは自身のペイン内のエージェントだけです。 同じマシン上の Terminal.app で起動した claude は表示されません(herdr はプロセススキャナではなくランタイムです)。

実機未自動テストの範囲: SwiftUI の長押しコンテキストメニューは UI 自動化で操作できないため、 メニュー → 確認ダイアログの遷移はコンパイルとユニットテストで検証しています。

ステップ 4

どこにいても権限プロンプトに応答する

Claude Code がコマンド実行の許可を求めて止まります。このサイトで「エージェントが人間を必要としている」ことを表す色は アンバーだけです。ロック画面へ届く通知にもその色が現れます。

iPhone のロック画面:m1-pro 上の claude が Bash の使用許可を求めている即時通知

ロック中の端末に届く質問 タイトルはエージェント名、本文には何をどこで尋ねているかが表示されます(例: Claude needs your permission to use Bash — m1-pro · pit)。 同じホストで複数エージェントが待っているときは 1 枚のカード(claude +2)にまとまります。

タップで直行 質問したまさにそのペインが開きます。本物のターミナルで内容を確認し、 デスクと同じキー操作で返答できます。

「許可」ボタンをあえて置かない理由 以前あったロック画面のボタンは、ペインへ盲目的にキー入力を送るものでした。 中身を読んで確認できることが価値のアプリで、読まずに承認させるのは誤ったトレードオフだったため廃止しました。

アプリを閉じていても届く仕組み

サスペンド中の iPhone ができない仕事を、あなたのホストが担います。ペインに状態を記録するフックが、 working は送らず attention と done だけを小さな送信スクリプト ~/.moshpit/moshpit-push.sh に渡します。スクリプトはあなたの端末だけが持つ鍵で通知を暗号化し、 暗号文を Moshpit のプッシュリレー経由で Apple へ送ります。リレーも Apple も 1 バイトも読めません。 エージェント名、コマンド、質問文は端末内の通知拡張機能で初めて復号されます。 ペアリングは通知有効化時に自動で行われ、あなたが承認する必要があるのは初回のフック導入だけです。

対象範囲の明確化。 送信スクリプトはエージェントフックと連動しており、フックは tmux ペインに状態を記録します。 そのためアプリ終了時のプッシュ通知を使うには、フック導入済みの tmux 下でエージェントを動かす必要があります。 純粋な herdr ペインでは、herdr 自身の agent_status が Moshpit 起動中 に Dynamic Island と通知を駆動し、 アプリ終了後は止まります。アプリを閉じた状態で通知を受けたい場合は、現時点では tmux ペインで Claude Code を実行してください。

うるさくしないための 4 つのルール

何でも通知するのは何も通知しないのと同じです。割り込む価値があるときだけ知らせます:

ルール意味
30 秒の猶予 30 秒以内にデスクで応答した質問は、どの端末にも通知されません。
ホストごとに 1 枚のカード 待機中のエージェントは「claude +2」のように 1 枚へ集約されます。鳴動したり集中モードを抜ける可能性があるのは 誰も待っていない → 誰かが待ち始めた 瞬間だけで、その後の増減は静かに更新されます。
完了音は 3 分以上のみ ターン完了時に音が鳴るのは 3 分以上かかった実行だけです。短いターンは画面を点灯させず静かに届きます。
待機放置エージェントは静か 意図的にプロンプトで止めているエージェントでは通知されず、1 日以上古い「要対応」は自動で完了扱いへ戻ります。

細かな配慮として、アプリ内でプロンプトを見れば既読扱いになり、再接続や再起動で同じ質問が何度も鳴り直すことはありません。

制御する 4 つのスイッチ

設定 → 通知。4 つすべて既定でオンです。

  • 通知 —「エージェントがあなたを必要とするとき通知」
  • ライブアクティビティ —「Dynamic Island にエージェントの状態を表示」
  • 通知音 —「エージェントがあなたを必要とするとき音を鳴らします」
  • ロック画面に詳細を表示 — オフにすると「作業中 / 要対応 / 完了」だけを表示し、 Bash: npm install といった具体的な内容はロック解除まで隠します。

通知 と ライブアクティビティ を両方オフにすると監視自体が止まります。 スイッチの下にある このホストを設定 では、接続中ホストのフック導入状況、プッシュ送信スクリプトの有無、 この端末とのペアリング状態を確認できます。

アンバーの点と感嘆符を表示する Dynamic Island:エージェントが要対応

ロック解除中 · 要対応 1 体が待機中ならアンバーの感嘆符、複数なら件数を表示します。長押しで展開すると、残りのエージェントも下に一覧表示されます。

ティールの点とライブタイマーを表示する Dynamic Island:エージェントが作業中

ロック解除中 · 作業中 Claude Code が稼働している間はティールとライブタイマーを表示。考え中と停止中が一目で見分けられます。

正直な制限事項

アプリをバックグラウンドに回すとどうなるか

ここまでの機能を頼りにする前に読んでおいてほしい内容です。アプリ停止中の隙間を埋めるのが暗号化プッシュですが、 それでも補えない点もそのまま書いておきます。

iOS が接続を停止し、ライブ表示は一時停止する

iOS がアプリをサスペンドすると、2 秒ごとの巡回も SSH ポーリングも止まります。 その間を埋めるのがステップ 4 のプッシュ経路です。ホスト上のフックが attention と done を検知し、 暗号化通知を直接送るため、画面ロック中・アプリ終了中でも届きます。

一方で、ライブアクティビティは隙間を跨げません。アプリが最後に見た状態を表示し続け、 サスペンド中は更新元が止まります。実機計測でも、バックグラウンド中にペインが要対応から作業中へ変わっても、 フォアグラウンドへ戻って最初のポーリングが完了するまで Dynamic Island の表示は変わりませんでした。

だから嘘をつかず「一時停止」と表示する

Moshpit                      2 working · 1 needs you
●  claude                   NEEDS YOU · 2m
   mac-studio · ~ · Tab 1
   Bash: npm install

… app suspended for two minutes …

Moshpit            paused — open Moshpit to refresh

ライブアクティビティには 120 秒の鮮度期限を設けており、古い「作業中」を出し続ける代わりに「一時停止」と正直に表示します。 ホーム画面ウィジェットは 180 秒で状態ドットをグレーに落とします。ステップ 4 の送信スクリプトが入っていれば、 その間もプッシュ通知は変わらず届き続けます。

フォアグラウンドでも、外部からの変更にはわずかな遅延がある

  • herdr のコントロールポーリングは動きがある間 2 秒 ごとに走り、3 回連続で変化がなければ 8 秒 間隔へ緩めます。 変化やプル更新があれば即座に 2 秒へ戻ります。
  • アプリ内で行った操作は直後に再取得するため即反映されます。ノート PC など外部からの変更は、反映まで最大 8 秒 かかることがあります。
  • 経過時間を秒単位ではなく 今、2分、1時間 12分 のように分単位で表示しているのもそのためです。 最大 8 秒の粒度しかない値に秒を付けて正確なふりをしない設計です。
  • herdr のソケット API にはイベント購読がありますが、CLI に subscribe コマンドがなく、iPhone からホストの Unix ソケットを直接開くこともできないため、 現時点ではポーリングが唯一の手段です。

同じペインに 2 台の Moshpit を繋ぐと奪い合いになる

herdr のダイレクトアタッチはペインごとに排他です。再接続時に自身の古いチャネルと衝突しないよう、 Moshpit は --takeover 付きでアタッチします。そのため 2 台の端末で同じペインを同時に開くと、 約 2 秒おきに所有権を奪い合うことになります。これは排他アタッチの仕様上、クライアント側だけでは防げません。

対策として、30 秒以内に意図しない切断が 3 回起きると 30 秒間一時停止し、 「別のクライアントがこのペインを使用中です — まもなく再試行します」と表示します。描画が再開すれば自動で消えます。 ノート PC で動かす herdr 自身の TUI はアタッチ枠を占有しないため併用できる見込みですが、この組み合わせは未検証です。

よくある疑問

このガイドを読んだあとによく出る質問

herdr は必須ですか?

いいえ。tmux でも 設定 → 通知 → エージェントフックをインストール(ホストを設定)から設定できます。 Claude Code の UserPromptSubmit、PreToolUse、Notification、 Stop フックを登録して tmux ペインに状態を記録します。編集前に ~/.claude/settings.json をバックアップし、 エージェントを妨げないよう常に終了コード 0 で終了し、重複登録も防ぎます。 フックなしではペイン出力とベル音からの推測にフォールバックします。なおホームの「新規エージェントタスク」は herdr 専用です。

Moshpit を閉じていても通知で起こしてもらえますか?

はい。そのためのプッシュ経路です。ホスト上のフックが端末専用の鍵で通知を暗号化し、Moshpit のリレー経由で送信します。 アプリ終了中・ロック中でも端末内の通知拡張機能が復号して表示します。 ただしステップ 4 の範囲注記のとおり、送信スクリプトは tmux ペイン向けのフックに乗るため、 この用途が主目的なら tmux 下でエージェントを動かしてください。静音ルールの詳細は プッシュ通知とライブアクティビティ をご覧ください。

Mosh はどうなりますか?

Wi-Fi と 5G の切り替えをまたぐシェルには Mosh が最適ですが、herdr のフレームプロトコルや tmux -CC は運べません。 Mosh 上では herdr 自身の TUI がターミナル内で動き、iPhone 画面幅の約 3 分の 1 をサイドバーが占めます(コントロールシートは別 SSH 経由で動作)。 このガイドでは SSH をおすすめします。詳しくは Mosh をご覧ください。

Claude Code は動いているのにエージェント一覧が空です。

ほぼ間違いなく herdr のペイン外で起動しています。herdr は自身のペインだけを監視するため、 Terminal.app や別 SSH セッションで起動した claude は見えません。 新規エージェントタスク で起動するか、herdr ペイン内で実行してください。 また herdr 0.7.3 ではエージェント名が返らないため、アイドル状態のエージェントは行が生成されません。

Moshpit は私のコードやプロンプトを読み取りますか?

アカウントも解析もなく、ターミナル通信はあなたが登録したサーバーとだけ行われます。 Moshpit が運用する唯一の要素はプッシュリレーですが、そこを通るのは解読不能な暗号文だけです。 ペインの外に出るのはフックが作る最大 80 文字の短いタイトル(実行中や質問中の内容)のみで、 それも暗号化されたまま届き、あなたの端末のロック画面でのみ復号されます。

次に読むべきドキュメントは?

接続フォームとホストキーの詳細は ホストと鍵、 herdr の用語と操作は herdr、 通知とライブアクティビティの詳細は プッシュ通知とライブアクティビティ をご覧ください。 接続できない・挙動がおかしい場合は トラブルシューティング から確認できます。

続けて読む: どこからでも自分のマシンへ接続する · ガイド一覧へ戻る