指南

從 iPhone 執行 Claude Code

這正是 Moshpit 誕生的核心場景。只要四個步驟:讓主機連得上、裝好 herdr、啟動 Claude Code,然後從鎖定畫面通知帶你進入的窗格裡回應權限請求。本頁出現的每段文字與指令,都來自實際上架版本與 Moshpit 真實執行的命令。

1 連上主機
填好 SSH 資訊、首次核對一次主機金鑰指紋,並把這條連線的終端機多工器選為 herdr。
2 啟動智能體
在 herdr 窗格裡輸入 claude,或讓 Moshpit 開出一個全新的 git worktree 並在裡面啟動 Claude Code。
3 放心放下手機
當 Claude Code 停下來請求權限時,鎖定畫面會立刻通知你——點一下直接跳進發問的那個窗格。

開始前你需要準備:一台已經能透過 SSH 連上的伺服器、一支執行 iOS 18 或更新版本的 iPhone,以及伺服器上已安裝好 Claude Code。Moshpit 不會替你安裝 Claude Code,也不會跟 Anthropic 通訊——它只負責驅動一個 shell,而 Claude Code 就是跑在裡面的程式。

herdr 並非強制。因為它能讓智能體狀態成為確切事實而非猜測,本指南會以 herdr 示範。走 tmux 路線同樣可行,詳細作法請見 tmux 控制模式 與 推播與即時動態。

步驟 1

讓主機連得上線

四個欄位加上一次指紋核對。只要你本來就能從筆電 ssh 進這台機器,這一步一分鐘就能搞定。

加入連線

在首頁點右上角的 +,表單分為幾個區塊:

  • 連線 — 名稱、主機、連接埠(預設 22)、使用者名稱。填好名稱和主機後,儲存就會亮起。
  • 登入方式 — 密碼 或 SSH 金鑰。金鑰可以是在設定 → SSH 金鑰產生的,或是直接貼進表單的 PEM 私密金鑰。
  • 進階 — 終端機多工器 選為 herdr。除非執行檔放在特別的路徑,否則自訂路徑留空即可;填入自訂路徑後系統會完全照字面執行,並略過能力偵測。

終端機多工器是依連線個別設定,而非全域套用。你的每台主機裝的工具不盡相同,做成全域預設只會製造更多「怎麼這台連不上」的困擾。

首次核對指紋

第一次連線時,握手會暫停,Moshpit 會顯示對方提供的主機金鑰指紋:

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 無法替你驗證指紋,因此直接附上可供比對的指令。若之後已儲存的主機金鑰發生變更,對話框會切換為 ⚠️ 主機金鑰已變更,並列印出新舊兩組指紋,預設按鈕為中斷連線,而信任新金鑰則標示為危險操作。

值得先知道的限制:目前 App 裡沒有列出或清除已信任主機金鑰的畫面。刪除連線不會忘記指紋,且信任紀錄只存在本機、不包含在備份中——換新手機時每台主機都會重新詢問一次。若主機確實合法重產了金鑰,在 ⚠️ 警告視窗點選接受是目前唯一的 App 內操作路徑。

此外,直接填在連線表單裡的密碼與 PEM 並不會加上 Face ID 鎖;只有在加入金鑰中開啟需要 Face ID 產生的金鑰,才會於每次讀取簽章時要求驗證。帶有密碼短語加密的私密金鑰在 inline 表單中也不支援直接貼入。

步驟 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 發行版官方套件庫中,官方打包僅涵蓋 Windows。因此 Moshpit 刻意不自動拼出 sudo apt-get install -y herdr——執行完只回傳「unable to locate package」會看起來像 App 出了 bug。

安裝腳本會把執行檔放在 ~/.local/bin,且刻意不修改你的任何 shell rc 檔。Moshpit 在偵測與啟動 herdr 時會自動把這個目錄加進 PATH,所以你在主機上不需要改任何設定。

沒裝的話,App 會直接告訴你

如果選了 herdr 卻連上一台尚未安裝的主機,你看到的會是一條可關閉的提示橫幅,而不是報錯中斷:

  • 橫幅提示:「這台主機上沒有 herdr,先以一般 shell 工作階段執行。」並附上安裝 herdr 按鈕。
  • 點開「在主機上安裝」輔助視窗,會預先填好正確指令並說明:「Moshpit 不會悄悄安裝任何東西。把下面的指令貼到你的 shell 執行,sudo 和輸出全程都看得到。」
  • 點在終端機執行會把指令貼進現有 shell,讓 sudo 提示與輸出全程公開可見;旁邊也有拷貝指令與重新偵測。
  • 連線依然正常可用,先給你一個一般 shell,而且絕不會悄悄幫你切去 tmux——tmux 與 herdr 的工作階段互不相通,擅自改接另一個只會讓你看到別處的工作畫面。

整合對應的 herdr 版本:本整合是以 herdr main / v0.8.0(protocol 19)設計,並在實機上以 0.7.3(protocol 16)驗證通過(也就是當時 brew install herdr 裝到的版本)。快照解碼器設計成缺少某個欄位時僅降級該項細節,不會讓整筆讀取失敗。

在 0.7.3 上可見的差異:它不會回報窗格執行的指令名稱,因此終端機頂列的第三段會退回顯示 pane N,而非顯示正在跑的程式名。但我們依然保留這段路徑,因為它是進入「選擇窗格」列表的唯一入口。

這篇教學請用 SSH,不要用 Mosh。Mosh 傳輸的是繪製後的畫面差異,會破壞行框協定,無法承載 herdr 的 frame protocol(同理也無法承載 tmux -CC)。透過 Mosh 連線時,herdr 會跑自己的全螢幕 TUI,Moshpit 只負責渲染畫面——在手機上這會讓 herdr 的側邊欄吃掉約三分之一寬度。控制面板列表仍可透過獨立的 SSH 側通道運作。

步驟 3

啟動 Claude Code

有兩種方式:在既有的窗格裡直接執行,或是讓 Moshpit 開出獨立的 git worktree 並於其中啟動。人在外面只拿手機時,第二種特別順手。

在既有的窗格裡執行

零學習成本

  • 在任一 herdr 窗格輸入 claude 就完成了
  • herdr 會透過監看窗格畫面自動辨識智能體
  • 不用多設任何東西,也不用多記新流程

新增智能體任務

一個 worktree、一個工作區、一個智能體

  • 單一張表單,從首頁的 智能體標題即可開啟
  • 在主機上開出全新 git worktree 並於其中啟動 Claude Code
  • 完全不碰你原本的工作樹
  • 僅限 herdr——tmux 沒有對應功能

無論哪種方式,herdr 預設都能從畫面內容推斷智能體狀態。如果你想讓 Claude Code 主動精準回報而非由畫面推斷,只要在主機執行一次 herdr integration install claude 即可。這更精準,但並非必要;不裝也能跑完本指南全部內容。

表單欄位逐一說明

任務區塊底部說明:「在主機上新開一個 git worktree,讓智能體在裡面工作。你現在的工作樹不會被動到。」

  • 儲存庫 — 下拉選單。Moshpit 會同時用兩種方式找候選項目:先用 git rev-parse --show-toplevel 解析所有已開啟窗格的工作目錄,再依修改時間掃描 $HOME。尋找時會顯示「正在尋找儲存庫…」;若都沒找到則顯示「沒找到。窗格都不在儲存庫裡,家目錄下也沒有」。最後一項永遠是其他…,點選後可手填儲存庫路徑。
  • 分支 — 送往主機前先在手機端驗證。空字串、空格、開頭的 - 或 /、結尾的 /、..、結尾的 .lock,以及字元 ~ ^ : ? * [ \ 都會被擋下並給出白話提示(例如「分支名稱不能有空格」),不合法的名稱不會送去主機。
  • 智能體 — 讀自 herdr server agent-manifests --json。預設優先選 claude,其次 codex,再來才是清單第一項(以前按字母排序時在實機上預設會選到 agy,所以改掉了)。

第一則訊息區塊底部說明:「選填。智能體啟動後會傳給它,留空就自己手動輸入。」按下開始後按鈕會變為正在啟動…,因為大型儲存庫檢出需要數十秒,按鈕如果毫無反應會讓人以為當機。

按下「開始」後實際執行了什麼

透過 SSH 依序執行三條指令,沒有任何隱藏動作,而且你輸入的每個字串進入 shell 前都會加上單引號保護。

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'          <- types the command and presses return

herdr 智能體 send 'w4:p1' '<first message>'   <- 2s later, only if you typed one

一個新 git worktree、一個新工作區、一個已經切進該目錄並聚焦的窗格。第二步刻意選用 pane run 而不是 智能體 start:因為 智能體 start --workspace 不會繼承 worktree 的目錄,會讓窗格落在錯的路徑。pane run 做的就跟你親手打字一模一樣,過程全程可見。

你最先看到的畫面

在實機驗證中,新工作區會出現在 ~/.herdr/worktrees/…/fix-scroll-jump,用 git worktree list 可確認分支確實建立,接著 Claude Code 啟動並停在信任目錄的確認提示。herdr 會把這個窗格標記為 智能體: claude / status: blocked,首頁的智能體區塊會立刻顯示 智能體 1 · NEEDS YOU。這第一個提示,就是你在步驟 4 要回應的內容。

完成後的清理

在首頁長按該工作區列 → 移除工作樹。這個選項只會出現在確實是 linked worktree 的工作區上,第一次送出的指令絕不會帶 --force:

  • 要移除「…」的工作樹嗎? — 「只刪除 ~/.herdr/worktrees 下的分支檢出,payments-api 本身不受影響。」
  • 只有在 herdr 因工作樹尚有未提交更動而拒絕時,才會跳出第二個確認視窗:「…」有尚未提交的更動 — 「這些更動只存在這裡。刪掉工作樹,它們就沒了。」按鈕為仍要刪除/保留,唯有明確點下刪除才會加上 --force。

這一步的限制,直接講清楚:

worktree 一律建在 ~/.herdr/worktrees/<repo>/<branch>,而不是儲存庫旁邊,這版也不提供自訂路徑選項——在手機上敲路徑並不划算。大型儲存庫檢出需要幾十秒。對已有未提交更動的儲存庫執行 git worktree add 預期能正常運作,但尚未實測驗證。

不會替你決定智能體參數。manifest 裡預設的 claude 指令是什麼,就跑什麼。像 --dangerously-skip-permissions 這類參數需要你在窗格裡自己輸入。

herdr 只看得到自己窗格裡的智能體。你在同一台電腦的 Terminal.app 裡開的 claude 不會出現在這裡——herdr 是執行環境,不是系統行程掃描器。這點確實有人踩過:開了五個閒置 herdr 窗格、另在外部終端機跑了一個忙碌的 claude,結果首頁如實顯示「沒有執行中的任務。新建一個,會替它單獨開一個工作樹。」,讓使用者以為出錯。

尚未以自動化在實機錄影驗證:長按右鍵選單本身。自動化工具無法驅動 SwiftUI 長按,因此選單 → 對話框 → 第二對話框的流程是由編譯檢查與單元測試把關,無實機錄影紀錄。

步驟 4

人在哪裡,都能回應權限提示

Claude Code 停下來問你能不能執行某條指令。琥珀色是整個網站裡唯一代表「智能體需要人類介入」的顏色,此刻它會直接以鎖定畫面通知的形式出現。

iPhone 鎖定畫面:Moshpit 時效性通知,顯示 claude 在 m1-pro 上需要 Bash 執行權限

鎖定畫面上的提問 標題是智能體名稱,內文寫明它在問什麼以及在哪裡——Claude needs your permission to use Bash — m1-pro · pit。同一台主機有多個智能體在等你時,會合併成單一張卡片:claude +2。

點一下直達 直接落進發問的那個窗格。在真正的終端機裡看清完整提問,再用跟電腦前一樣的按鍵回答它。

刻意移除「允許」按鈕 早期版本的鎖定畫面按鈕會盲目送出一個按鍵到窗格裡。一款核心價值是「讓你看清楚再答」的 App,讓人沒看內容就點允許根本本末倒置——所以我們把它拿掉了。

App 沒在執行時,通知怎麼送到手機

被系統暫停的 iPhone 做不到的事,交由你的主機完成。替窗格打標記的同一套 hooks 會把 attention 與 done(絕不送 working)交給精簡發送腳本 ~/.moshpit/moshpit-push.sh,它會用只有這部手機才有的金鑰加密通知,再把密文交給 Moshpit 推播中繼伺服器與 Apple。兩者連一個位元組都看不懂:智能體名稱、指令與提問本身都在你手機的通知延伸功能裡解密,鎖定畫面也同樣適用。第一次在主機啟用通知時會自動完成配對;唯一需要你確認的只有首次安裝 hooks。

適用範圍直接說明:這套推播發送機制掛在智能體 hooks 上,而 hooks 標記的是 tmux 窗格——因此 App 關閉後仍能送達的推播路徑,目前需要讓智能體跑在已安裝 hooks 的 tmux 下。在純 herdr 窗格裡,由 herdr 自己的 agent_status 驅動動態島與通知(僅限 Moshpit 執行期間),App 關閉後推播就會停止。如果你最在意的是關掉 App 也能被叫醒,現階段請先在 tmux 窗格裡執行 Claude Code。

讓通知保持安靜的四條規則

什麼都通知等於什麼都沒通知,每則提醒都必須值得打斷你:

規則實際意義
擱置滿 30 秒 在電腦桌前 30 秒內順手回答掉的提問,手機永遠不會收到打擾。
每台主機一張卡片 所有在等你的智能體會合併成一張摘要(如「claude +2」)。只有從沒人等 → 有人等的瞬間會響鈴並穿透專注模式,後續異動都只會靜音更新卡片。
跑滿 3 分鐘才響完成音 一輪任務至少跑滿三分鐘,完成通知才會發聲;短任務只會靜靜排進通知中心,不會點亮螢幕。
閒置智能體保持安靜 被你刻意停在提示字元上的閒置智能體不會發任何提醒;放了一整天的過期「在等你」狀態也會自動歸位為已完成。

細節同樣講究:在 App 裡看過提問就視為已讀,重新連線或重開 App 絕不會把早就提醒過你的問題再響一次。

控制通知的四個開關

位於設定 → 通知,四項預設全部開啟。

  • 通知 —「智能體需要你時通知」
  • 即時動態 —「在動態島顯示智能體工作階段的狀態」
  • 提示音 —「智能體需要你時播放提示音」
  • 在鎖定畫面顯示詳細內容 —「顯示智能體在跑什麼、在問什麼、剛做完哪條提示詞。關掉就不顯示這些內容」。關閉後仍會看到工作中/在等你/已完成,但會隱藏像 Bash: npm install 這類明細。

把通知和即時動態都關掉,就完全不會監看任何狀態。開關下方的設定這台主機會列出目前連線主機的詳情:哪些智能體裝了 hooks、推播腳本是否就緒、這部手機的配對狀態——設定本身在連線時即會自動處理。

動態島顯示琥珀色圓點與驚嘆號:有智能體正在等你

解鎖狀態 · 在等你 一個智能體卡住時膠囊會顯示琥珀色驚嘆號,多個時則顯示數量。膠囊空間只放得下一個,長按展開就能看到下方其他等待中的智能體。

動態島顯示青色圓點與即時碼表:智能體正在工作中

解鎖狀態 · 工作中 Claude Code 運行時呈青色並附帶即時碼表。正在思考和卡住等你,一眼就分得出來。

老實說清楚

把 App 切到背景後會發生什麼事

在你完全仰賴上述流程之前,這一段務必先讀。端對端加密推播補上了大部分空檔,但也有些它覆蓋不到的地方,這裡一併寫明。

iOS 會暫停連線,即時介面也會跟著暫停

一旦 iOS 把 App 暫停在背景,每 2 秒一次的巡檢與 SSH 輪詢都會跟著停止。能跨過這道鴻溝的是步驟 4 的推播路徑:主機上的 hooks 偵測到 attention 與 done 時自行寄出加密提醒——不需要活著的連線,手機鎖定、App 關閉都收得到。

跨不過這道鴻溝的是即時動態(Live Activity)。它只能顯示 App 最後一次讀到的狀態,App 被暫停時就沒人餵給它新資料。實機測試確認:把 Moshpit 切到背景後,即使窗格從等待中恢復成工作中,動態島仍會維持舊畫面,直到切回前景完成一次輪詢才更新。

所以動態島會老實寫「已暫停」,而不是騙你

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 秒的過期門檻(相當於錯過兩次巡檢),超過就誠實顯示「已暫停,打開 Moshpit 重新整理」,而不會假裝還在「工作中」。主畫面小工具的門檻為 180 秒,過期後所有狀態圓點都會轉灰。只要步驟 4 的推播腳本已就緒,推播通知仍會照常送達。

就算在前景,外部造成的變動也有延遲

  • herdr 的控制輪詢在畫面有變動時每 2 秒跑一次,連續三次讀到相同結果後會放緩到 8 秒。一有變動或下拉重新整理,就立刻切回 2 秒。
  • 你在 App 裡面做的操作會立即刷新——每次異動都會緊接著重讀。但在別處發生的事(筆電、其他客戶端、智能體狀態變化)最多可能需要 8 秒才會反映出來。
  • 這也是為什麼耗時一律以分鐘顯示(剛剛、2m、1h 12m),絕不顯示秒數。背後的資料解析度最粗可達 8 秒,印出秒數只是假裝精準。
  • herdr 的 socket API 雖然有事件訂閱功能,但它的 CLI 並未開放 subscribe 指令,手機也無法直接打開你主機上的 Unix socket。輪詢是目前唯一可行的機制。

兩個 Moshpit 客戶端同時連同一個窗格會互搶

herdr 的直連 attach 是單一窗格獨佔的。Moshpit 連線時必須帶 --takeover,否則斷線重連一定會撞到自己遺留的舊通道。因此如果兩支手機同時開啟同一個窗格,彼此大約每兩秒就會把控制權搶來搶去——這是獨佔式直連的本質,客戶端無法繞過。

Moshpit 的應對方式:30 秒內發生三次非預期中斷時,會暫停 30 秒並跳出提示「這個窗格正被另一個客戶端占用,稍後會重試」,等畫面恢復繪製就自動消失。筆電上執行 herdr 自己的 TUI 不會佔用 attach 名額,理論上「筆電+手機」同時用是安全的,但這個組合尚未經過實測。

補充問答

照著這篇指南做通常會問的問題

我一定要用 herdr 嗎?

不用。如果用 tmux,到設定 → 通知 → 設定主機即可一鍵註冊 Claude Code 的 UserPromptSubmit、PreToolUse、Notification 與 Stop hooks,將狀態標記在 tmux 窗格上。安裝前會先備份 ~/.claude/settings.json,腳本永遠 exit 0 絕不卡住智能體,重複執行也會自動去重。不裝 hooks 時 Moshpit 也能靠讀取窗格輸出與終端機響鈴運作,但那屬於推測模式。另外首頁的獨立智能體區塊目前僅支援 herdr。

Moshpit 關掉的時候,真的叫得醒我嗎?

可以——推播路徑正是為此設計的。你主機上的 hooks 會用只有你手機擁有的金鑰加密通知,再透過 Moshpit 中繼伺服器送出;就算手機鎖定、App 關閉,通知延伸功能也能在鎖定畫面解密顯示。請留意步驟 4 的範圍說明:推播發送掛在標記 tmux 窗格的智能體 hooks 上,若最在意關 App 收推播,請把智能體跑在 tmux 裡。靜音規則(30 秒緩衝、每台主機一張卡片、跑滿三分鐘才響完成音、閒置靜音)詳見推播與即時動態。

那 Mosh 呢?

如果你要的是撐過 Wi-Fi 切 5G 的 shell,Mosh 是絕佳選擇,但它無法承載 herdr 的 frame protocol 或 tmux -CC。走 Mosh 時,herdr 會在終端機裡跑自己的 TUI,側邊欄會佔掉手機約三分之一寬度;控制列表仍由獨立的 SSH 側通道支援。執行本篇指南的流程請用 SSH。細節請看 Mosh 文件。

Claude Code 明明在跑,首頁的智能體區塊卻是空的。

幾乎可以確定它不是跑在 herdr 窗格裡。herdr 是透過監看自己的窗格來辨識智能體,你在 Terminal.app 或另一個 SSH 工作階段啟動的 claude 對它來說完全不可見。請用新增智能體任務啟動,或切進 herdr 窗格再跑。此外在 herdr 0.7.3 上還會有另一個現象:它不回報智能體名稱,所以閒置中的智能體不會顯示出列。

Moshpit 會讀取我的程式碼、提示詞或其他資料嗎?

Moshpit 沒有帳號、沒有分析工具,終端機流量只會往返你自己加入的伺服器。唯一由 Moshpit 營運的元件是推播中繼伺服器,而它經手的只有它自己也解不開的密文——通知在你的主機端就用只有你手機擁有的金鑰加密了。唯一會離開窗格的資料是 hook 擷取的短標題(智能體正在執行或詢問的內容,上限 80 字元),全程加密傳輸並只在你自己的鎖定畫面上顯示。

接下來可以看什麼?

想了解完整的連線欄位與主機金鑰行為,請看主機與金鑰;想熟悉 herdr 的名詞與操作,請看 herdr 文件;想深入了解通知與即時動態細節,請看推播與即時動態。如果連不上或行為怪異,請從疑難排解開始。

接著閱讀 隨時隨地連回你的機器 · 返回指南列表