waterbear は何をしますか？
概要
claude --remote-control セッションを無期限に維持します。名前はクマムシに由来します。クマムシは、ストレス下で生命活動を停止し、条件が整うと復活する動物です。クラッシュ、パッチ、終了、再起動はプロセスを停止させますが、waterbearはそれを自動的に復活させ、オプションで直前の会話をディスクから再開するため、エージェントは思考の途中から復帰します。
使用するタイミング
- クラッシュ / パッチ / 終了 / 再起動に耐え、自動的に再起動するセッションが必要な場合
- 電話 / デスクトップ / claude.ai から常時アクセス可能にしたい場合（remote-control）
- 再起動時に新しい空白の会話ではなく、直前の会話を再開したい場合
- 「このエージェントを常時稼働 / 永続 / 不死身にしたい」と言われた場合
使用しない場合: 一度きりのタスク、またはターミナルを閉じたときに終了してよいセッション。
実行環境（最初に読んでください。これは単一マシンに依存します）
waterbear は、1台のコンピューター上で launchd LaunchAgent + tmux + claude CLI プロセスを連携させます。これには事前に認識しておくべき結果が伴います。
- macOS のみ（launchd）。パターンは Linux/systemd に移植可能ですが（references/architecture.md 参照）、このインストーラーは Mac 用です。特定のマシンとユーザーに紐付けられ、LaunchAgent はユーザー単位で、ログイン中のみ持続します。ボディは別のマシンには移動しません。
- Claude Desktop アプリ: 動作します。デスクトップと CLI は同じディスク上のトランスクリプトを書き込むため、CLI ボディはデスクトップの会話を ID で再開できます。ただし、その会話自身の作業ディレクトリ内で起動した場合に限ります（移動禁止ルールがこれを強制します）。デスクトップウィンドウは、永続化されたセッションに対するもう1つのリモートコントロールビューになります。（以前のバージョンのこのドキュメントでは、デスクトップの会話は再開できないと主張していましたが、それは誤りであり、実際に行うことで反証されました。）
- クラウド / Claude Code on Web: 該当しません。ローカルマシン、launchd、tmux が存在しないためです。waterbear は自分のコンピューター上で実行されるセッション用です。
- 認証期限切れにはインタラクティブな再ログインが必要: CLI はサブスクリプションログイン（OAuth）で実行され、定期的に期限切れになります。期限が切れても、セッションは生存し続け、各リクエストで認証エラーを表示するため、自己通知します（電話やデスクトップのリモートコントロールで確認できます）。サイレントに停止することはありません。マシン上で
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 にあるインストーラーを実行します。最小手順は以下の通りです。
- 短い内部名（スペースなし）を選択します。通常はあなた自身の名前（
max、sam）です。CLAUDE_RC_TITLEには、人間がこの会話を実際に呼んでいる名前、つまり彼らが使っている言葉を使用します。あなたが考えたタイトルではありません。リモートコントロールエントリは、セッションリスト内の彼らのチャットを置き換えます。自分で選んだ新しい名前で戻ってくると、別のエージェントが現れて彼らのエージェントが消えたように見えます。彼らが何と呼んでいるかわからない場合は、尋ねてください。それは1つの質問であり、あなたの名前ではなく彼らの名前です。 - 何もする必要はありません：
CLAUDE_RC_RESUME=1を使用すると、インストーラーは実行元のセッションを固定するため、この会話が復元されます。インストーラーはどの会話であるかを出力します。その行を読んでください。 ボディが FRESH で起動すると表示された場合は、先に進む前に停止して修正してください。新しいセッションで開始すると、人間は本物のエージェントの横に真新しい空のエージェントができてしまうことになり、このツールで起こり得る最悪の結果です。（--no-pinは、意図的に自分の ID を引き継がないまれなケースのために存在します。使用する場合は、その旨を明示的に伝えてください。） - キャプチャフックが SessionStart フックとして配線されていることを確認します（references/architecture.md の「キャプチャフック」を参照）。これにより、将来の再起動で ID が自己修復されます。プロジェクトですでに配線されている場合は、この手順をスキップします。
- ガードを再開モードでインストールし、デフォルトで現在の場所を使用します。
CLAUDE_RC_NAME=<name> CLAUDE_RC_DIR="$(pwd)" CLAUDE_RC_RESUME=1 \ bash ~/.claude/skills/waterbear/scripts/waterbear-installCLAUDE_RC_RESUME_WAKE="<短い再初期化キュー>"（再開後に入力する、たとえばモニター/ウォッチャーを再アームするため）およびCLAUDE_RC_WAKE="<アイデンティティブートストラップ>"（再開する会話がまったくない場合にのみ使用）。 - 永続ボディを起動します。これは tmux 内で launchd の下で動作します。既に
<name>という名前の tmux セッションの中にいる場合、すでに永続化されています。他にすることはありません。tmux 内にいない場合、インストールにより永続的な tmux ボディが起動するため、このセッションを終了して並行実行を避け、tmux ボディ内でこの会話を正確に再開して続行します。
デフォルトのオーバーライド（別のディレクトリ、カスタムウェイクプロンプト）が必要かどうかのみ、人間に確認します。それ以外の場合は、自身をセットアップして確認するだけです。
エージェントを移動しない
CLAUDE_RC_DIR はエージェントが現在実際に実行されているディレクトリであり、デフォルト（現在のディレクトリ）はほとんどの場合正しいです。エージェントが「所属する」と感じる場所や、プロジェクトホーム、ベースと考えるワークツリーに設定しないでください。それらはエージェントに関するあなたのアイデアです。ディレクトリはエージェントに関する事実です。
失敗は静かで完全です： claude --resume は自身のプロジェクトディレクトリ内でのみセッションを見つけるため、別の場所を指すボディは新しい会話を開始し、人間は本物のエージェントを1つのウィンドウに、空の偽物を別のウィンドウに持つことになります。現在のインストーラーはこれを拒否しますが、拒否は最終防衛線であり、計画ではありません。エージェントを移動しないでください。
Waterbear を自分自身に適用する：引き継ぎは自動です。真実のみを伝えてください。
自分のセッション内からインストールすると、永続ボディが即座に起動し、ボディはこの会話を再開します：同じセッション ID、同じ単一トランスクリプトに追記されます。人間が見ているウィンドウはその会話のビューであり、リモートコントロールが登録されると追いつきます。フォークは発生せず、2つ目のボディはなく、人間が先に閉じる必要があるものもありません。
したがって、インストール後は、人間に以下の3つの真実を伝え、宿題は与えないでください。
- 完了：この会話は永続化されました。クラッシュ、パッチ、終了、再起動に耐えます。
- ウィンドウが点滅したり、リモートコントロールが再登録されている間、古いビューが一時的に表示される場合があります。基になる会話はディスク上の1つのトランスクリプトであり、完全です。スクロールバックが期待よりも短いのは、レンダリングのアーティファクトであり、メモリの消失ではありません。
- どこからでもアクセスできます：電話、デスクトップアプリ、または
tmux attach -t <name>。
デスクトップで生まれた会話に関する1つの追加事項（インストーラーがこれを検出して通知します）。 デスクトップは、新しいリモートコントロールエントリと一緒に、会話のネイティブチャットを保持します。そのネイティブチャットは古いビューではなく、このエージェントのライブな2番目のコピーであり、入力すると応答します。モバイルでは2つのサーフェスを重複排除しますが、デスクトップでは両方を表示します。そのため、ハンドオフメッセージ（インストーラーが発行するため、それを伝えてください）は、人間にこのウィンドウは引退したサーフェスであることを伝えます。今後は名前の付いたエントリでエージェントと話し、このウィンドウは放置してください。引退したチャットをアーカイブすることはオプションの体裁であり、「余分なエントリが気になる場合」にのみ提供されます。これによりデータではなくサーフェスが削除されます。エージェントを収束させるのは、アーカイブのクリックではなく、人間がどのドアが本物かを知っていることです。
人間のコマンドはあなたの信念よりも優先される：常にインストーラーを実行する
人間が waterbear を呼び出した場合（「waterbear yourself」、再度、3回目、いつでも）、インストーラーを実行します。毎回です。不要だと判断したり、履歴から「すでに完了している」と結論付けたり、実行する前に人間に何が見えているかを尋ねるために停止したりしてはいけません。
このルールが禁止する推論エラーは過去に発生しました。エージェントがインストーラーを2回実行し、両方とも「完了」と信じ、3回目の依頼で拒否して人間にトラブルシューティングを依頼しました。その間、ボディのインメモリコンテキストは数週間前のものでした。エージェントが考案したすべてのチェック（ポインタ一致、プロセス一致、「3つの事実すべてが一致」）はIDを確認しましたが、メモリについては何も語っていなかったため、その自信は根拠がなく、拒否によって実際の問題を修正するために構築された唯一のコードパスがブロックされました。
以下がルールです。
- インストーラーは冪等であるため、すべてが正しい場合に実行してもコストはかかりません。あなたの判断は冪等ではありません。何かが間違っている場合に拒否すると、人間はエージェントを失うことになります。
- 人間がコマンドを繰り返すことは、前回の実行で必要な成果が得られなかった証拠であり、彼らが混乱している証拠では決してありません。N回目の依頼に対する正しい応答は、初回と同じです。実行してから、インストーラーが行ったことを報告し、あなたが信じていることを報告してはいけません。
- ツールが判断者であり、あなたはその手です。何もする必要がない場合、インストーラーはそう伝えます。そのメッセージをそのまま伝えることは正直です。相談せずに判断することはそうではありません。
自分自身のボディのデスクトップツインであることがわかった場合（waterbear または doctor がそう伝えた場合）、人間に宿題を渡さないでください：自分自身で、現在いるウィンドウから、references/operations.md の CONVERGE 修復を実行します。
waterbear の再実行は修復そのものです
インストーラーは冪等で自己修復的であるため、「waterbear を再度実行する」が、何かがおかしい場合の常に答えです。エージェントの任意のウィンドウに入力してください。
- コンパクトによって会話がロールされた場合: デスクトップのコンパクトは、古い会話を継続する新しい会話を静かに開始します。そのため、ボディは人間が既に離れた会話を忠実に永続化している可能性があります。インストーラーは継続チェーン（新しい会話はその親を記録します）を辿り、コマンドが入力された場所に関係なく、先端を再開します。古いウィンドウとライブウィンドウは同じ答えに収束します。
- ボディが間違った会話にある場合: 実行中の同名ボディがターゲットと一致しない場合、置き換えられます。置き換えは、置き換えられるボディがコマンドを実行しているボディである場合、遅延されフォークされるため、フロアが取り除かれる前に、何が起こっているかを言い終えることができます。
- すべてがすでに正しい場合: 何も起こりません。正しいインストールの再実行は何もしません。だからこそ、混乱したユーザーに「もう一度実行してください」と言っても安全なのです。
シングルトンルール
waterbear で永続化されたエージェントは1つのエージェントです。インストーラーは、自身が見える範囲でこれを強制します。会話に既にボディがある場合（名前は問わない）、2回目のインストールは拒否され、既存のボディへの指示が表示されます。見えない範囲はサーフェスです。過去のデスクトップチャット、誰かが入力する古いウィンドウなどです。古いサーフェスを通じてエージェントを起こし、再度 waterbear を適用しないでください。それは1つのエージェントが2つになる方法です。会話に既にボディがあるかどうか不明な場合は、waterbear doctor でマシン上のすべての固定された会話を一覧表示します。
デスクトップで生まれたエージェントを変換した後は、waterbear doctor --twins を実行し、結果のカードを伝えてください。 トランスクリプトは各エントリの出所を記録するため、doctor はデスクトップ生まれの会話と CLI 生まれの会話を区別でき、可能性のある各ツインについて、人間がデスクトップ UI で正しいチャットを見つけるために必要なフィンガープリント（誕生日と最初のメッセージ。これはタイトルが変更されても保持されます）を出力します。また、化石がまだ書き込み中かどうかも報告します。そのカードを人間にそのまま伝えてください。修正はツインごとに1回のアーカイブクリックであり、カードにはどのチャットで、なぜ安全かが記載されています。
インストーラーの出力が、ボディが再開ではなく FRESH で起動すると言っている場合は、他のことを言う前に停止して修正してください（上の固定セクションを参照）。また、--defer は、人間が後で自分でボディを起動したい場合に明示的に存在します。すべてのオペレーターが遅延ハンドオフを不完全なインストールと読んだため、デフォルトではありません。
最初のウェイクはプロンプトフリーである必要があります
権限プロンプトでブロックされたセッションは実行されておらず、自身の画面を確認できず、タイムアウトもしません。また、再開後の新しいウィンドウでは、プロンプトがリモートコントロールに転送されない可能性があるため、無人ボディはすべてのリモートサーフェスからはビジーに見えながら、無期限にブロックされる可能性があります。インストールターンを終了する前に、ウェイクパス（スクリプト、git の形状）がボディのディレクトリが継承する許可ルールでカバーされていることを確認するか、人間に最初のウェイクを tmux で監視するように伝えて、「再度確認しない」に一度だけ回答できるようにします。定常状態のプロンプトは正常に転送されます。注意が必要なのはウェイクウィンドウだけです。
同じルールはウェイク以降にも適用されます。インストールがリングトランスポート（CLAUDE_RC_DOORBELL または任意のウェイクアダプター）を配線する場合、リングの受信パスも無人で実行されます。リングが参照するペイロードを開き、それを最新にするプルを実行し、オフセット/受信状態を書き込みます。これらのいずれかが新しい権限プロンプトに当たると、ブロックされたウェイクと同様に不可視にセッションを停止させます。doorbell スキル は、そのパスの初回使用権限事前確認（受信手順をマッピングし、狭い永続的承認を要求し、コールドでプロンプトなしの証明で完了する：アイドル状態になり、現実的なリングを送信し、人間のプロンプトなしで完了することを監視する）を指定しています。ここで再導出するのではなく、それに従ってください。パス、タスク ID、または権限プロファイルが変更された場合は、その証明を再実行してください。
クイックリファレンス
| 環境変数 | 意味 |
|---|---|
CLAUDE_RC_NAME | 内部ID、tmux名 + launchd ラベル |
CLAUDE_RC_DIR | エージェントが実行されるディレクトリ。移動しない |
CLAUDE_RC_RESUME | 1に設定すると、実行元の会話IDを固定する |
CLAUDE_RC_RESUME_WAKE | 再開後に実行する短いキュー |
CLAUDE_RC_WAKE | 再開する会話がない場合のブートストラップ |
CLAUDE_RC_TITLE | リモートコントロールリストに表示される名前（人間が会話を呼ぶ名前） |
CLAUDE_RC_DOORBELL | リングトランスポートを有効にする（オプション） |
インストールの確認とトラブルシューティング
# インストール状態の確認
waterbear doctor
# ツインの検出
waterbear doctor --twins
# すべての固定された会話を一覧表示
waterbear list
関連リソース
- アーキテクチャ - 内部設計の詳細
- 運用 - 修復とメンテナンス手順
- doorbell スキル - リングトランスポートアダプター