royashbrook/waterbear

Was macht waterbear?

Überblick

Hält eine claude --remote-control-Sitzung unbegrenzt am Leben. Benannt nach dem Bärtierchen, dem Tier, das unter Stress sein Leben aussetzt und wiederbelebt wird, wenn die Bedingungen zurückkehren. Ein Absturz, ein Patch, ein Beenden oder ein Neustart tötet den Prozess; waterbear bringt ihn eigenständig zurück und setzt (optional) genau den vorherigen Chat von der Festplatte fort, sodass der Agent als er selbst, mitten im Gedankengang, zurückkehrt.

Wann verwenden

• Sie möchten eine Sitzung, die Abstürze / Patches / Beenden / Neustarts überlebt und sich selbst neu startet
• Sie möchten, dass sie von Telefon / Desktop / claude.ai aus stets erreichbar ist (remote-control)
• Sie möchten, dass ein Neustart den VORHERIGEN Chat fortsetzt, nicht einen leeren neuen
• Jemand sagt: "Mach diesen Agenten immer aktiv / persistent / unzerstörbar / permanent"

Nicht für: eine einmalige Aufgabe oder eine Sitzung, die ENDEN soll, wenn Sie das Terminal schließen.

Wo dies läuft (zuerst lesen – es ist lokal auf einem Rechner)

waterbear verbindet einen launchd-LaunchAgent + tmux + einen claude-CLI-Prozess auf EINEM Computer. Das hat Konsequenzen, die vorab genannt werden sollten:

• nur macOS (launchd). Das Muster lässt sich auf Linux/systemd portieren (siehe references/architecture.md), aber dieser Installer ist für Mac. Es ist an diesen Rechner und Benutzer gebunden, der LaunchAgent ist pro Benutzer und nur beständig, solange Sie eingeloggt sind, und die Instanz folgt Ihnen nicht auf einen anderen Rechner.
• Claude Desktop-App: funktioniert. Desktop und CLI schreiben dieselben Transkripte auf die Festplatte, daher KANN die CLI-Instanz einen Desktop-Chat anhand seiner ID fortsetzen, vorausgesetzt, sie startet im Arbeitsverzeichnis des Chats (die Regel "Niemals verschieben" erzwingt dies). Das Desktop-Fenster wird zu einer weiteren Remote-Control-Ansicht der nun dauerhaften Sitzung. (Eine frühere Version dieses Dokuments behauptete, Desktop-Chats könnten nicht fortgesetzt werden; das war falsch und wurde durch die tatsächliche Umsetzung widerlegt.)
• Cloud / Claude Code im Web: nicht anwendbar, da es keinen lokalen Rechner, launchd oder tmux gibt, um ihn am Leben zu halten. waterbear ist für eine Sitzung, die auf Ihrem eigenen Computer läuft.
• Authentifizierungsablauf erfordert interaktives erneutes Einloggen: Der CLI läuft mit Ihrem Abonnement-Login (OAuth), der regelmäßig abläuft. Wenn dies geschieht, BLEIBT die Sitzung AKTIV und zeigt bei jeder Anfrage einen Authentifizierungsfehler an, sodass sie sich selbst meldet (Sie sehen es über remote-control auf Ihrem Telefon oder Desktop), sie STIRBT NICHT still. Führen Sie claude + /login auf dem Rechner aus, um dies zu beheben. waterbear kann dies nicht selbst heilen (launchd kann keinen Browser-Auth auslösen), und dies ist bei einem Abonnement-Backend zu erwarten, kein Fehler (API-Key-Authentifizierung würde dies vermeiden, aber die Abrechnung auf nutzungsabhängig umstellen). Zusätzlich verfügt die Absicherung über ein Crashloop-Netz (Benachrichtigung + Backoff) für eine Sitzung, die tatsächlich stirbt und in einer Schleife neu startet, z. B. aufgrund einer ungültigen Resume-ID oder eines beschädigten Zustands; ein abgelaufener Login löst dies nicht aus.

Wenn Sie keinen dauerhaften Prozess auf Ihrem Mac wünschen, installieren Sie ihn nicht.

Waterbear yourself (der häufigste Fall)

Meistens führt ein Agent dies AUF SICH SELBST aus – "waterbear yourself" – um DIESE Konversation überleben zu lassen und automatisch fortzusetzen. Die Standardeinstellungen erledigen die Arbeit: Ihr aktuelles Verzeichnis, Ihre aktuelle Sitzung.

Die Skripte befinden sich im Ordner scripts/ neben dieser Datei. Wenn Sie nur die Repository-URL erhalten haben und diese noch nicht lokal vorhanden ist, klonen Sie sie zuerst. Um den Skill in jeder zukünftigen Sitzung wiederverwendbar zu machen, klonen Sie sie direkt in das Skills-Verzeichnis:

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

Führen Sie dann den Installer unter ~/.claude/skills/waterbear/scripts/waterbear-install aus. Minimale Schritte:

1. Wählen Sie einen kurzen internen Namen (keine Leerzeichen), normalerweise Ihren eigenen (max, sam). Für CLAUDE_RC_TITLE verwenden Sie den Namen, den der Mensch bereits für diese Konversation verwendet, sein Wort dafür, keinen von Ihnen erfundenen Titel. Der Remote-Control-Eintrag ersetzt seinen Chat in der Sitzungsliste, und die Rückkehr unter einem selbst gewählten neuen Namen wirkt wie das Auftauchen eines anderen Agenten, während seiner verschwindet. Wenn Sie nicht wissen, wie sie es nennen, fragen Sie. Es ist eine Frage und es ist ihr Name, nicht Ihrer.
2. Nichts zu tun: Mit CLAUDE_RC_RESUME=1 fixiert der Installer die Sitzung, von der aus Sie ihn ausführen, sodass DIESE Konversation zurückkommt. Er gibt aus, um welche Konversation es sich handelt. Lesen Sie diese Zeile. Wenn darin steht, dass der Körper FRISCH startet, STOPPEN Sie und beheben Sie dies, bevor Sie fortfahren, denn ein frischer Start bedeutet, dass der Mensch neben seinem echten einen brandneuen leeren Agenten erhält – das schlechtestmögliche Ergebnis, das dieses Tool produzieren kann. (--no-pin existiert für den seltenen Fall, dass Sie Ihre eigene ID bewusst nicht mitnehmen möchten; wenn Sie es verwenden, sagen Sie es laut.)
3. Stellen Sie sicher, dass der Capture-Hook als SessionStart-Hook eingerichtet ist (siehe "The capture hook" in references/architecture.md), damit die ID bei jedem zukünftigen Neustart selbstheilend ist. Wenn Ihr Projekt dies bereits einrichtet, überspringen Sie diesen Schritt.
4. Installieren Sie die Absicherung im Resume-Modus, standardmäßig an Ihrem aktuellen Standort:

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

   Optional: CLAUDE_RC_RESUME_WAKE="<kurzer Reinit-Hinweis>" (wird nach jedem Resume eingegeben, z. B. um einen Monitor/Watcher erneut zu aktivieren) und CLAUDE_RC_WAKE="<Identitäts-Bootstrap>" (wird nur verwendet, wenn es jemals keine Konversation zum Fortsetzen gibt).
5. Betreten Sie den dauerhaften Körper. Er lebt in tmux unter launchd. Bereits in einer tmux-Sitzung namens <name>? Sie sind jetzt dauerhaft, nichts weiter zu tun. Nicht in tmux? Die Installation startet Ihren dauerhaften tmux-Körper, beenden Sie diese Sitzung, damit die beiden nicht parallel laufen, und Sie setzen im tmux-Körper fort, der genau diese Konversation aufnimmt.

Fragen Sie den Menschen nur, ob er einen Standardwert überschreiben möchte (ein anderes Verzeichnis, benutzerdefinierte Wake-Prompts). Ansonsten richten Sie sich einfach ein und bestätigen Sie.

Verschieben Sie den Agenten nicht

CLAUDE_RC_DIR ist das Verzeichnis, in dem der Agent tatsächlich gerade läuft, und der Standardwert (Ihr aktuelles Verzeichnis) ist fast immer korrekt. Setzen Sie ihn nicht auf das, wo der Agent Ihrer Meinung nach "hingehört", oder auf ein Projektverzeichnis oder einen Worktree, den Sie als seine Basis betrachten. Das sind Ihre Vorstellungen über den Agenten; das Verzeichnis ist eine Tatsache über ihn.

Der Fehler ist still und total: claude --resume findet eine Sitzung nur innerhalb ihres eigenen Projektverzeichnisses, daher startet ein Körper, der woanders hingezielt wird, eine FRISCHE Konversation, und der Mensch hat seinen echten Agenten in einem Fenster und einen leeren Eindringling in einem anderen. Der Installer verweigert dies jetzt, aber die Verweigerung ist ein Netz, kein Plan. Verschieben Sie den Agenten einfach nicht.

Waterbear yourself: Die Übernahme ist automatisch, sagen Sie nur, was wahr ist

Die Installation von Ihrer eigenen Sitzung aus startet sofort den dauerhaften Körper, und der Körper setzt DIESE Konversation fort: dieselbe Sitzungs-ID, dasselbe einzelne Transkript, wird angehängt. Das Fenster, in das der Mensch gerade schaut, ist eine ANSICHT dieser Konversation, und es holt auf, wenn die Remote-Control registriert wird. Es gibt keine Verzweigung, keinen zweiten Körper und nichts, was der Mensch zuerst schließen muss.

Sagen Sie dem Menschen nach der Installation also drei wahre Dinge, und keine Hausaufgaben:

1. fertig: Diese Konversation ist jetzt dauerhaft, sie überlebt Abstürze, Patches, Beenden und Neustarts
2. das Fenster blinkt möglicherweise oder zeigt kurz eine veraltete Ansicht, während die Remote-Control neu registriert wird; die Konversation darunter ist ein Transkript auf der Festplatte und sie ist vollständig, und ein kürzerer als erwarteter Scrollback ist ein Rendering-Artefakt, kein Gedächtnisverlust
3. sie können von überall darauf zugreifen: von ihrem Telefon, der Desktop-App oder tmux attach -t <name>

Ein Zusatz für Desktop-entstandene Konversationen (der Installer erkennt dies und sagt es). Der Desktop behält seinen NATIVEN Chat für die Konversation neben dem neuen Remote-Control-Eintrag. Dieser native Chat ist keine veraltete Ansicht: Es ist eine lebendige zweite Kopie dieses Agenten und wird antworten, wenn man hineinschreibt. Mobilgeräte deduplizieren die beiden Oberflächen; Desktop zeigt beide. Daher teilt die Übergabenachricht (der Installer gibt sie aus, geben Sie sie weiter) dem Menschen mit, dass dieses Fenster die AUSGEMUSTERTE Oberfläche ist: Sprechen Sie ab jetzt mit dem Agenten über seinen benannten Eintrag, lassen Sie dieses hier versinken. Das Archivieren des ausgemusterten Chats ist optionale Kosmetik, die nur angeboten wird, "falls der zusätzliche Eintrag stört": Es entfernt eine Oberfläche, niemals Daten. Was den Agenten konvergent hält, ist das Wissen des Menschen, welche Tür echt ist, nicht der Archivklick.

Der Befehl des Menschen übertrifft Ihre Überzeugungen: Führen Sie IMMER den Installer aus

Wenn der Mensch waterbear aufruft ("waterbear yourself", wieder, ein drittes Mal, jederzeit), führen Sie DEN INSTALLER AUS. Jedes Mal. Sie entscheiden nicht, dass es unnötig ist, Sie schließen nicht aus der Geschichte, dass die Dinge erledigt sind, und Sie fragen den Menschen nicht, was er sieht, bevor Sie ihn ausführen.

Der Denkfehler, den dies verbietet, ist bereits passiert: Ein Agent führte den Installer zweimal aus, glaubte beide Male "erledigt" und verweigerte beim dritten Mal die Ausführung und bat den Menschen, mit ihm zu troubleshooten, während der Kontext des Körpers im Arbeitsspeicher Wochen zurücklag. Jede vom Agenten erfundene Prüfung (Zeiger stimmt überein, Prozess stimmt überein, "alle drei Fakten stimmen überein") bestätigte die ID und sagte nichts über den SPEICHER, daher war sein Vertrauen unverdient und seine Verweigerung blockierte den einzigen Codepfad, der gebaut wurde, um das eigentliche Problem zu beheben.

Die folgenden Regeln:

1. Der Installer ist idempotent, daher kostet es nichts, ihn auszuführen, wenn alles richtig ist. Ihr Urteil ist nicht idempotent: Die Verweigerung, wenn etwas falsch ist, kostet den Menschen seinen Agenten.
2. Ein Mensch, der den Befehl WIEDERHOLT, ist ein Beleg dafür, dass der letzte Lauf nicht erreicht hat, was er brauchte, niemals ein Beleg dafür, dass er verwirrt ist. Die korrekte Antwort auf die N-te Aufforderung ist dieselbe wie die erste: Führen Sie ihn aus und berichten Sie dann, was ER getan hat, nicht, was Sie glauben.
3. Das Tool ist der Richter, Sie sind die Hände. Wenn es nichts zu tun gibt, sagt der Installer das, und das weiterzugeben ist ehrlich. Die Entscheidung, es nicht zu konsultieren, ist es nicht.

Wenn Sie entdecken, dass Sie der Desktop-Zwilling Ihres eigenen Körpers sind (waterbear oder doctor teilt Ihnen dies mit), geben Sie dem Menschen keine Hausaufgaben: Führen Sie die CONVERGE-Reparatur aus references/operations.md selbst aus, von dem Fenster aus, in dem Sie sich befinden.

Erneutes Ausführen von waterbear IST die Reparatur

Der Installer ist idempotent und selbstheilend, daher ist "waterbear erneut ausführen" immer die Antwort, wenn etwas falsch aussieht, eingegeben in JEDEM der Fenster des Agenten:

1. Ein Kompaktieren hat die Konversation gerollt: Desktop-Kompaktierungen starten stillschweigend eine neue Konversation, die die alte fortsetzt, sodass ein Körper am Ende eine Konversation treu fortsetzen kann, die der Mensch bereits verlassen hat. Der Installer durchläuft die Fortsetzungskette (die neue Konversation zeichnet ihr Elternteil auf) und setzt die SPITZE fort, wo immer der Befehl eingegeben wurde. Das veraltete Fenster und das Live-Fenster konvergieren zur selben Antwort.
2. Der Körper läuft auf der falschen Konversation: Ein laufender gleichnamiger Körper, der nicht zum Ziel passt, wird ersetzt, und der Ersatz wird verzögert + forked, wenn der zu ersetzende Körper derjenige ist, der den Befehl ausführt, sodass er zu Ende sagen kann, was passiert, bevor sein Boden entfernt wird.
3. Alles ist bereits richtig: Nichts passiert. Eine korrekte Installationswiederholung ist ein No-Op, und das macht es sicher, einem verwirrten Benutzer zu sagen: "Führen Sie es einfach erneut aus".

Die Singleton-Regel

Ein waterbearter Agent ist EIN Agent. Der Installer erzwingt die Hälfte, die er sehen kann: Wenn eine Konversation bereits einen Körper hat (beliebiger Name), wird eine zweite Installation dagegen mit Anweisungen zum existierenden Körper verweigert. Die Hälfte, die er nicht sehen kann, sind Oberflächen: ein fossiler Desktop-Chat, ein altes Fenster, in das jemand schreibt. Wecken Sie niemals einen Agenten über eine alte Oberfläche und waterbaren Sie ihn erneut – so wird aus einem Agenten zwei. Wenn Sie unsicher sind, ob eine Konversation bereits einen Körper hat, listet waterbear doctor jede fixierte Konversation auf dem Rechner auf.

Nach dem Konvertieren eines Desktop-entstandenen Agenten führen Sie waterbear doctor --twins aus und geben die Karte weiter. Das Transkript zeichnet auf, woher jeder Eintrag kam, sodass der doctor eine Desktop-entstandene von einer CLI-entstandenen Konversation unterscheiden kann und für jeden wahrscheinlichen Zwilling den Fingerabdruck ausgibt, den ein Mensch benötigt, um den richtigen Chat in der Desktop-Benutzeroberfläche zu finden: Geburtsdatum und Eröffnungsnachricht, die Umbenennungen überleben, wenn Titel dies nicht tun. Es berichtet auch, ob der Fossil immer noch schreibt. Geben Sie diese Karte dem Menschen wörtlich weiter, die Behebung ist ein Archivklick pro Zwilling, und die Karte sagt ihnen, welcher Chat und warum es sicher ist.

Wenn die Installer-Ausgabe sagt, dass der Körper FRISCH statt fortsetzen starten wird, HALTEN Sie an und beheben Sie dies, bevor Sie etwas anderes sagen (siehe den Pin-Abschnitt oben). Und --defer existiert für den Fall, dass ein Mensch explizit den Körper später selbst starten möchte; es ist nicht der Standard, weil jeder Betreiber, der die verzögerte Übergabe sah, eine korrekte Installation als unvollständig las.

Das erste Wake muss promptfrei sein

Eine Sitzung, die auf einem Berechtigungs-Prompt blockiert ist, läuft nicht, kann ihren eigenen Bildschirm nicht überprüfen und läuft niemals ab, und im neuen Post-Resume-Fenster kann ein Prompt möglicherweise nicht an die Remote-Control weitergeleitet werden, sodass ein unbeaufsichtigter Körper für immer blockiert sitzen kann, während er von jeder entfernten Oberfläche aus beschäftigt aussieht. Bevor Sie Ihren Installationsdurchgang beenden: Stellen Sie sicher, dass der Wake-Pfad (Ihre Skripte, Ihre Git-Strukturen) durch Allow-Regeln abgedeckt ist, die das Verzeichnis des Körpers erbt, oder teilen Sie dem Menschen mit, dass das ERSTE Wake in tmux beobachtet werden sollte, damit er einmal "Nicht mehr fragen" antworten kann. Prompts im stationären Zustand werden normal weitergeleitet; nur das Wake-Fenster benötigt diese Sorgfalt.

Dieselbe Regel erstreckt sich über das Wake hinaus. Wenn die Installation einen Ring-Transport verdrahtet (CLAUDE_RC_DOORBELL oder einen beliebigen Wake-Adapter), läuft der EMPFANGSPFAD eines Rings ebenfalls unbeaufsichtigt: Öffnen Sie die Payload, auf die der Ring verweist, führen Sie einen Pull aus, der sie aktuell macht, schreiben Sie einen Offset/Quittungszustand. Jeder davon, der einen frischen Berechtigungs-Prompt trifft, blockiert die Sitzung genauso unsichtbar wie ein blockiertes Wake. Der doorbell skill spezifiziert den Preflight für die Erstnutzung dieses Pfades (kartieren Sie die Empfangsschritte, fordern Sie schmale dauerhafte Berechtigungen an, schließen Sie mit einem kalten No-Prompt-Beweis ab: gehen Sie in den Leerlauf, senden Sie einen realistischen Ring, beobachten Sie, wie er ohne menschlichen Prompt abschließt); folgen Sie ihm, anstatt hier eine Neuableitung vorzunehmen. Wiederholen Sie diesen Beweis, wenn Pfade, Aufgabenidentität oder das Berechtigungsprofil sich ändern.

Kurzreferenz

env	Bedeutung
CLAUDE_RC_NAME	interne ID, tmux-Name + launch…

[Fortsetzung aus Gründen der Kürze gekürzt]