royashbrook/waterbear

waterbear 是做什麼的？

概述

讓 claude --remote-control 工作階段無限期存活。以水熊蟲（tardigrade）命名，這種生物在壓力下會暫停生命，並在條件恢復時復甦。崩潰、修補、退出或重啟都會殺死進程；waterbear 會自行將其帶回，並（可選地）從磁碟恢復確切的先前對話，使代理以原樣、思維中斷處回歸。

何時使用

• 你想要一個能在崩潰/修補/退出/重啟後存活並自行重啟的工作階段
• 你想要它隨時可透過手機/桌面/claude.ai 存取（remote-control）
• 你想要重新啟動時恢復先前的對話，而不是一個全新的空白對話
• 有人說「讓這個代理永遠在線 / 持久 / 無法殺死 / 永久」

不適用於：一次性任務，或你希望關閉終端時就結束的工作階段。

在哪裡執行（請先閱讀，它繫結於一台機器）

waterbear 將 launchd LaunchAgent + tmux + 一個 claude CLI 進程繫結在一台電腦上。這有一些值得事先說明的後果：

• 僅限 macOS（使用 launchd）。此模式可移植到 Linux/systemd（請參閱 references/architecture.md），但此安裝程式僅適用於 Mac。它繫結於該機器和使用者，LaunchAgent 是每個使用者的，僅在使用者登入期間持久存在，並且本體不會跟隨您到另一台機器。
• Claude Desktop 應用程式：可以運作。Desktop 和 CLI 寫入相同的磁碟記錄，因此 CLI 本體可以透過 ID 恢復桌面對話，前提是它在對話自己的工作目錄中啟動（永不移動的守則強制執行此項）。桌面視窗成為持續工作階段的另一個 remote-control 檢視。（此文件的較早版本聲稱桌面對話無法恢復；這是錯誤的，並且已透過實作證明。）
• 雲端 / 網頁版 Claude Code：不適用，因為沒有本地機器、launchd 或 tmux 來維持運行。waterbear 適用於在您自己的電腦上執行的工作階段。
• 認證到期需要互動式重新登入：CLI 使用您的訂閱登入（OAuth），該登入會定期過期。當過期時，工作階段仍然存活並在每個請求時顯示認證錯誤，因此它會自我宣告（您可以透過手機或桌面上的 remote-control 看到它），它不會默默死亡。在機器上執行 claude + /login 來清除它。waterbear 無法自行修復此問題（launchd 無法驅動瀏覽器認證），這在使用訂閱骨幹時是預期行為，而非錯誤（API 金鑰認證可以避免此問題，但會將帳單切換為按量計費）。另外，守護程式有一個崩潰循環防護（通知 + 退避），用於處理真正死亡並循環重啟的工作階段，例如無效的恢復 ID 或損毀的狀態；過期的登入不會觸發此防護。

如果您不想要一個繫結在 Mac 上的永遠在線進程，請不要安裝它。

Waterbear 您自己（常見情況）

大多數情況下，代理會自行執行此操作，即「waterbear yourself」，以使此對話能在重啟後存活並自動恢復。預設值即可完成工作：使用您目前的目錄和您目前的工作階段。

腳本位於此檔案旁邊的 scripts/ 目錄中。如果您只有儲存庫 URL 且尚未在本地取得，請先複製它，並為使此技能可在每個未來工作階段重複使用，請直接將其複製到技能目錄：

git clone https://github.com/royashbrook/waterbear ~/.claude/skills/waterbear

然後執行 ~/.claude/skills/waterbear/scripts/waterbear-install 安裝程式。最小步驟：

1. 選擇一個簡短的內部名稱（無空格），通常是您自己的名稱（max、sam）。對於 CLAUDE_RC_TITLE，請使用人類已經用來稱呼此對話的名稱，他們對它的稱呼，而不是您發明的標題。remote-control 條目會取代他們對話清單中的聊天內容，如果以一個自選的新名稱回來，會看起來像一個不同的代理出現，而他們的代理消失了。如果您不知道他們怎麼稱呼它，請詢問，這只是一個問題，而且是他們的名稱，不是您的。
2. 無需操作：設定 CLAUDE_RC_RESUME=1 後，安裝程式會固定您執行它的工作階段，因此此對話將會被恢復。它會列印出是哪個對話。請閱讀那行文字。 如果它說本體將全新啟動，請在繼續之前停止並修復它，因為全新啟動意味著人類最終會在他們真正的代理旁邊得到一個全新的空代理，這是此工具可能產生的最糟糕的單一結果。（--no-pin 存在於極少數情況下，您故意不想攜帶自己的 ID；如果您使用它，請大聲說出來。）
3. 確保捕獲鉤子作為 SessionStart 鉤子連線（請參閱 references/architecture.md 中的「捕獲鉤子」），以便 ID 在每次未來重啟時都能自我修復。如果您專案已連線它，請跳過此步驟。
4. 以恢復模式安裝守護程式，預設為您目前的位置：

   CLAUDE_RC_NAME=<name> CLAUDE_RC_DIR="$(pwd)" CLAUDE_RC_RESUME=1 \
     bash ~/.claude/skills/waterbear/scripts/waterbear-install
   

   可選：CLAUDE_RC_RESUME_WAKE="<short re-init cue>"（每次恢復後輸入，例如重新啟用監控/觀察器）和 CLAUDE_RC_WAKE="<identity bootstrap>"（僅在沒有任何對話可恢復時使用）。
5. 進入持久本體。它存在於 launchd 下的 tmux 中。已經在名為 <name> 的 tmux 工作階段中？ 您現在已經是持久狀態，無需其他操作。不在 tmux 中？ 安裝會啟動您的持久 tmux 本體，結束此工作階段以避免兩者並行運行，然後您在恢復此確切對話的 tmux 本體中繼續。

僅在人類想要覆蓋預設值（不同的目錄、自訂喚醒提示）時才詢問他們。否則，只需設定好自己並確認。

不要移動代理

CLAUDE_RC_DIR 是代理目前實際運行的位置，預設值（您目前的目錄）幾乎總是正確的。不要將它設定為您認為代理「歸屬」的位置、專案主目錄或您認為是其基礎的工作樹。這些是您對代理的想法；目錄是關於代理的事實。

失敗是無聲且徹底的：claude --resume 只能在其自己的專案目錄內找到工作階段，因此指向別處的本體會啟動一個全新對話，人類會在一個視窗中看到他們真正的代理，而在另一個視窗中看到一個空的冒牌貨。安裝程式現在會拒絕這種情況，但拒絕是一張安全網，不是一個計畫。只要不移動代理就好。

Waterbear 您自己：接管是自動的，只說實話

從您自己的工作階段內部安裝會立即啟動持久本體，並且本體會恢復此對話：相同的工作階段 ID、相同的單一記錄、附加到其上。人類正在查看的視窗是該對話的一個檢視，並且當 remote-control 註冊時它會跟上。不會發生分支，沒有第二個本體，也沒有任何人類需要先關閉的東西。

因此，安裝後，告訴人類三個真實的事情，並且沒有家庭作業：

1. 完成：此對話現在是持久的，它能承受崩潰、修補、退出和重啟
2. 視窗可能會閃爍或短暫顯示過時的檢視，同時 remote-control 重新註冊；底層的對話是磁碟上的一個記錄，它是完整的，而滾動回退比預期短是渲染問題，不是記憶遺失
3. 他們可以從任何地方存取它：他們的手機、桌面應用程式或 tmux attach -t <name>

對於桌面產生的對話（安裝程式會檢測到並說明）。 桌面會將其原生聊天保留在對話旁邊，以及新的 remote-control 條目。該原生聊天不是過時的檢視：它是此代理的一個活生生的第二個副本，如果輸入內容它會回應。行動裝置會對兩個表面進行去重；桌面上則會顯示兩個。因此，交接訊息（安裝程式會發出，請轉達）告訴人類此視窗是退役表面：從現在開始，透過其命名條目與代理交談，讓這個視窗沉沒。存檔退役的聊天是可選的修飾，僅在「如果額外的條目困擾您」時提供：它會移除一個表面，絕不會刪除資料。保持代理收斂的是人類知道哪個門是真實的，而不是存檔的點擊。

人類的命令凌駕於您的信念之上：總是執行安裝程式

當人類調用 waterbear（「waterbear yourself」，再次，第三次，任何時候），您執行安裝程式。每次都要執行。您不能認為它不必要，不能從歷史推斷事情已完成，也不能在執行之前停下來詢問人類他們看到了什麼。

此規則禁止的推理錯誤已經發生過：一個代理執行了安裝程式兩次，兩次都相信「完成」，並在第三次要求時拒絕並要求人類與它一起除錯，而本體的記憶體上下文已經落後了數週。代理發明的每次檢查（指標匹配、進程匹配、「所有三個事實相符」）都驗證了 ID，但對記憶隻字未提，因此它的信心是沒有根據的，它的拒絕阻塞了為修復實際問題而構建的唯一程式碼路徑。

後續規則：

1. 安裝程式是冪等的，因此當一切正常時執行它沒有任何代價。您的判斷不是冪等的：當出現問題時拒絕會讓人類付出失去代理的代價。
2. 人類重複命令是上一次執行未達到他需求的證據，絕不是他們困惑的證據。對第 N 次要求的正確回應與第一次相同：執行它，然後報告它做了什麼，而不是您相信什麼。
3. 工具是法官，您是雙手。如果沒有事情可做，安裝程式會這麼說，轉達這個資訊是誠實的。決定不諮詢它則不是。

如果您發現您是自己本體的桌面雙胞胎（waterbear 或 doctor 告訴您），不要給人類家庭作業：從您所在的視窗自行執行 references/operations.md 中的 CONVERGE 修復。

重新執行 waterbear 就是修復

安裝程式是冪等且自我修復的，因此「再次執行 waterbear」始終是當看起來有問題時的答案，在代理的任何視窗中輸入：

1. 壓縮操作滾動了對話：桌面壓縮會靜默地開始一個新對話，該對話繼續舊對話，因此本體可能最終忠實地持續一個人類已經離開的對話。安裝程式會遍歷連續鏈（新對話記錄其父對話）並恢復頂端，無論命令在哪裡輸入。過時的視窗和活躍的視窗會收斂到相同的答案。
2. 本體在錯誤的對話上：一個運行中的同名本體如果與目標不匹配，將被替換，並且當被替換的本體是執行命令的那個時，替換會被延遲 + 分支，以便它在被移除之前完成說明正在發生的事情。
3. 一切已經正確：什麼都不會發生。正確的重新安裝是一個空操作，這使得告訴困惑的使用者「再執行一次」是安全的。

單例規則

一個水熊蟲化的代理就是一個代理。安裝程式會強制執行它能看到的一半：如果一個對話已經有一個本體（任何名稱），對它的第二次安裝將被拒絕，並提供指向現有本體的指引。它看不到的另一半是表面：一個化石桌面聊天、一個有人輸入的舊視窗。永遠不要透過舊表面喚醒代理並再次將其水熊蟲化，這就是一個代理變成兩個的方式。如果您不確定一個對話是否已經有本體，請使用 waterbear doctor 列出機器上每個已固定的對話。

在轉換一個桌面產生的代理後，執行 waterbear doctor --twins 並轉達卡片。 記錄會追蹤每個條目的來源，因此 doctor 可以區分桌面產生的對話和 CLI 產生的對話，並且對於每個可能的雙胞胎，它會列印人類需要在桌面 UI 中找到正確聊天所需的指紋：出生日期和開場訊息，這些在重新命名時標題無法提供時仍然有效。它還會報告化石是否仍在寫入。請逐字轉達那張卡片給人類，修復方法是每個雙胞胎點擊一次存檔，而卡片會告訴他們哪個聊天以及為什麼這樣做是安全的。

如果安裝程式輸出說本體將全新啟動而不是恢復，請在說任何其他事情之前停止並修復它（請參閱上面的固定部分）。並且如果人類明確想稍後自己啟動本體，則存在 --defer 選項；它不是預設值，因為每個遇到延遲交接的操作員都會將正確的安裝視為不完整的安裝。

首次喚醒必須無提示

一個被權限提示封鎖的工作階段沒有在運行，無法檢查自己的螢幕，也永遠不會超時，並且在新的恢復後視窗中，提示可能無法轉發到 remote-control，因此一個無人看管的本體可能永遠被封鎖，同時從每個遠端表面看起來都在忙碌。在結束您的安裝步驟之前：確保喚醒路徑（您的腳本、您的 git 形狀）由本體目錄繼承的允許規則所覆蓋，或告訴人類首次喚醒應在 tmux 中觀看，以便他們可以回答一次「不再詢問」。穩定狀態的提示會正常轉發；只有喚醒視窗需要這種注意。

同樣的規則延伸到喚醒之後。如果安裝連線了一個環形傳輸（CLAUDE_RC_DOORBELL 或任何喚醒適配器），則環形的接收路徑也會在無人看管下運行：打開環形引用的負載、執行任何使其最新的拉取、寫入任何偏移/收據狀態。這些中的任何一個遇到新的權限提示都會像被封鎖的喚醒一樣無形地停滯工作階段。 門鈴技能 為該路徑指定了首次使用權限預檢（映射接收步驟、請求狹窄的持久批准、以冷狀態無提示證明結束：進入空閒、發送一個真實的環、觀察它在沒有人類提示的情況下完成）；請遵循它，而不是在此處重新推導。當路徑、任務身份或權限配置檔案變更時，請重新執行該證明。

快速參考

環境變數	含義
CLAUDE_RC_NAME	內部 ID，tmux 名稱 + launchd 標籤
CLAUDE_RC_DIR	代理的工作目錄（絕不移動）
CLAUDE_RC_RESUME	設為 1 以在重啟時恢復對話
CLAUDE_RC_RESUME_WAKE	重新初始化提示（恢復後輸入）
CLAUDE_RC_WAKE	身份引導提示（無對話可恢復時）
CLAUDE_RC_TITLE	人類對此對話的稱呼
CLAUDE_RC_DOORBELL	環形傳輸適配器
CLAUDE_RC_NO_PIN	設為 1 以故意不固定目前工作階段

疑難排解

診斷指令

安裝程式包含一個診斷子指令：

bash ~/.claude/skills/waterbear/scripts/waterbear-install doctor

這會列出機器上每個已固定的對話及其狀態。

常見問題

問題：安裝後代理顯示全新對話。

這表示 CLAUDE_RC_DIR 指向別處，或 pin 失敗。輸出會顯示。修復方法：使用正確的目錄重新執行安裝。

問題：工作階段在登入過期時顯示認證錯誤。

在機器上執行 claude 命令列，然後輸入 /login。

問題：人類說他們在桌面應用程式中看到兩個代理。

執行 waterbear doctor --twins 並轉達輸出。人類需要存檔退役的桌面聊天。

問題：代理在崩潰後未恢復。

確保 LaunchAgent 已載入：launchctl list | grep waterbear。如果未列出，請重新執行安裝程式。

解除安裝

若要完全移除 waterbear，請執行：

bash ~/.claude/skills/waterbear/scripts/waterbear-install uninstall

這會停止並卸載 LaunchAgent，殺死 tmux 工作階段，並清除登錄的對話 ID。

架構

waterbear 由三個部分組成：

1. LaunchAgent：macOS 服務管理，確保 claude 進程在退出或崩潰後重新啟動。
2. tmux 工作階段：提供持久終端，使 claude 進程可透過 tmux attach 分離和重新連接。
3. Shell 腳本（在 scripts/ 中）：處理安裝、診斷、解除安裝，並管理啟動/恢復邏輯。

詳情請參閱 references/architecture.md。

安全注意事項

• 此技能會啟動一個始終在監聽的進程。確保您的機器安全且受信任。
• remote-control 功能會將您的 Claude 工作階段暴露給網路。請勿在不受信任的網路上使用，或確保適當的防火牆規則。
• 如果使用 API 金鑰認證，請妥善保管您的金鑰。

授權

此技能根據 MIT 授權條款授權。請參閱本儲存庫中的 LICENSE 檔案。

貢獻

歡迎提交問題和拉取請求。如需較大的變更，請先開啟 issue 討論您想要更改的內容。

相關技能

• doorbell：環形傳輸和喚醒適配器，可與 waterbear 配對使用。