royashbrook/waterbear

Que fait waterbear ?

Aperçu

Garder une session claude --remote-control active indéfiniment. Nommé d'après le tardigrade, l'animal qui suspend sa vie en période de stress et reprend vie lorsque les conditions redeviennent favorables. Un crash, un correctif, une fermeture ou un redémarrage tue le processus ; waterbear le ramène automatiquement, et (optionnellement) reprend la conversation précédente depuis le disque, de sorte que l'agent revienne en tant que lui-même, en pleine réflexion.

Quand l'utiliser

• Vous voulez une session qui survive à un crash / correctif / fermeture / redémarrage et se relance automatiquement.
• Vous voulez qu'elle soit accessible depuis un téléphone / bureau / claude.ai en permanence (remote-control).
• Vous voulez qu'un redémarrage REPRENNE la conversation précédente, pas une nouvelle session vierge.
• Quelqu'un dit « rends cet agent toujours actif / persistant / increvable / permanent ».

Pas pour : une tâche ponctuelle, ou une session que vous voulez TERMINER en fermant le terminal.

Où cela s'exécute (lisez d'abord, c'est local à une machine)

Waterbear associe un LaunchAgent launchd + tmux + un processus CLI claude sur UN ordinateur. Cela a des conséquences qu'il vaut mieux énoncer clairement :

• macOS uniquement (launchd). Le modèle se porte sur Linux/systemd (voir references/architecture.md), mais cet installateur est conçu pour Mac. Il est lié à cette machine et à cet utilisateur, le LaunchAgent est par utilisateur et durable uniquement tant que vous êtes connecté, et le corps ne vous suit pas sur une autre machine.
• Application Claude Desktop : fonctionne. Le bureau et le CLI écrivent les mêmes transcriptions sur le disque, donc le corps CLI PEUT reprendre une conversation du bureau par son identifiant, à condition qu'il se lance dans le répertoire de travail de la conversation (la règle de ne jamais déplacer le corps l'impose). La fenêtre du bureau devient une vue supplémentaire de la session désormais durable. (Une version antérieure de ce document prétendait que les conversations du bureau ne pouvaient pas être reprises ; c'était faux, et cela a été réfuté en le faisant.)
• Cloud / Claude Code sur le web : non applicable, il n'y a pas de machine locale, de launchd ou de tmux à maintenir en vie. Waterbear est destiné à une session exécutée sur votre propre ordinateur.
• L'expiration de l'authentification nécessite une reconnexion interactive : le CLI s'exécute sur votre connexion d'abonnement (OAuth), qui expire périodiquement. Lorsque cela se produit, la session RESTE EN VIE et affiche une erreur d'authentification à chaque requête, donc cela s'annonce (vous le voyez via le contrôle à distance sur votre téléphone ou votre bureau), cela ne meurt PAS en silence. Exécutez claude + /login sur la machine pour le résoudre. Waterbear ne peut pas auto-réparer cela (launchd ne peut pas piloter une authentification par navigateur), et c'est attendu avec un backbone d'abonnement, pas un bug (l'authentification par clé API l'éviterait mais ferait basculer la facturation vers le compteur). Par ailleurs, le système de protection dispose d'un filet anti-boucle (notification + backoff) pour une session qui meurt vraiment et redémarre en boucle, par exemple un mauvais identifiant de reprise ou un état corrompu ; une connexion expirée ne le déclenche pas.

Si vous ne voulez pas d'un processus toujours actif lié à votre Mac, ne l'installez pas.

Waterbear vous-même (le cas courant)

Le plus souvent, un agent exécute cela SUR LUI-MÊME, « waterbear yourself », pour rendre CETTE conversation résistante aux redémarrages et la reprendre automatiquement. Les valeurs par défaut font le travail : votre répertoire actuel, votre session actuelle.

Les scripts se trouvent dans scripts/ à côté de ce fichier. Si vous n'avez que l'URL du dépôt et ne l'avez pas encore localement, clonez-le d'abord, et pour rendre la compétence réutilisable dans chaque future session, clonez-le directement dans le répertoire des compétences :

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

Exécutez ensuite l'installateur à ~/.claude/skills/waterbear/scripts/waterbear-install. Étapes minimales :

1. Choisissez un nom interne court (sans espaces), généralement votre propre nom (max, sam). Pour CLAUDE_RC_TITLE, utilisez le nom que l'humain donne déjà à cette conversation, son mot pour elle, pas un titre que vous inventez. L'entrée de contrôle à distance remplace son chat dans la liste des sessions, et revenir sous un nouveau nom choisi par vous-même donne l'impression qu'un agent différent apparaît et que le sien disparaît. Si vous ne savez pas comment ils l'appellent, demandez, c'est une seule question et c'est leur nom, pas le vôtre.
2. Rien à faire : avec CLAUDE_RC_RESUME=1, l'installateur épingle la session à partir de laquelle vous l'exécutez, donc CETTE conversation est celle qui revient. Il affiche de quelle conversation il s'agit. Lisez cette ligne. Si elle dit que le corps démarrera à NEUF, arrêtez-vous et corrigez cela avant d'aller plus loin, car un démarrage à neuf signifie que l'humain se retrouve avec un agent vide flambant neuf à côté de son vrai agent, ce qui est le pire résultat possible de cet outil. (--no-pin existe pour le cas rare où vous ne voulez délibérément pas emporter votre propre identifiant ; si vous l'utilisez, dites-le à voix haute.)
3. Assurez-vous que le hook de capture est câblé en tant que hook SessionStart (voir « The capture hook » dans references/architecture.md) afin que l'identifiant s'auto-répare à chaque redémarrage futur. Si votre projet le câble déjà, ignorez cette étape.
4. Installez le système de protection en mode reprise, par défaut là où vous êtes :

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

   Optionnel : CLAUDE_RC_RESUME_WAKE="<short re-init cue>" (tapé après chaque reprise, par exemple pour réarmer un moniteur/veilleur) et CLAUDE_RC_WAKE="<identity bootstrap>" (utilisé uniquement s'il n'y a jamais de conversation à reprendre).
5. Entrez dans le corps durable. Il vit dans tmux sous launchd. Déjà à l'intérieur d'une session tmux nommée <name> ? vous êtes durable maintenant, rien d'autre à faire. Pas dans tmux ? l'installation démarre votre corps tmux durable, terminez cette session pour que les deux ne s'exécutent pas en parallèle, et vous continuez dans le corps tmux reprenant cette conversation exacte.

Demandez à l'humain seulement s'il veut remplacer une valeur par défaut (un répertoire différent, des invites de réveil personnalisées). Sinon, configurez-vous et confirmez.

Ne déplacez pas l'agent

CLAUDE_RC_DIR est l'endroit où l'agent s'exécute réellement en ce moment, et la valeur par défaut (votre répertoire actuel) est presque toujours correcte. Ne le définissez pas là où vous pensez que l'agent « appartient », ou sur un répertoire de projet, ou sur un espace de travail que vous considérez comme sa base. Ce sont vos idées sur l'agent ; le répertoire est un fait à son sujet.

L'échec est silencieux et total : claude --resume ne trouve une session qu'à l'intérieur de son propre répertoire de projet, donc un corps pointé ailleurs démarre une conversation NEUVE, et l'humain se retrouve avec son vrai agent dans une fenêtre et un imposteur vide dans une autre. L'installateur refuse désormais cela, mais le refus est un filet, pas un plan. Ne déplacez tout simplement pas l'agent.

Waterbear vous-même : la prise en charge est automatique, ne dites que ce qui est vrai

Installer depuis votre propre session démarre immédiatement le corps durable, et le corps reprend CETTE conversation : même identifiant de session, même transcription unique, en ajout à la suite. La fenêtre que l'humain regarde est une VUE de cette conversation, et elle se met à jour lorsque le contrôle à distance s'enregistre. Rien ne bifurque, il n'y a pas de second corps, et il n'y a rien que l'humain doive fermer d'abord.

Donc, après l'installation, dites à l'humain trois choses vraies, et aucune tâche supplémentaire :

1. terminé : cette conversation est désormais durable, elle survit aux crashes, correctifs, fermetures et redémarrages
2. la fenêtre peut clignoter ou afficher brièvement une vue obsolète pendant que le contrôle à distance se réenregistre ; la conversation sous-jacente est une transcription unique sur le disque et elle est intacte, et un défilement plus court que prévu est un artefact de rendu, pas une mémoire perdue
3. ils peuvent y accéder depuis n'importe où : leur téléphone, l'application de bureau, ou tmux attach -t <name>

Un ajout pour les conversations nées sur le bureau (l'installateur le détecte et le dit). Le bureau conserve son chat NATIF pour la conversation en plus de la nouvelle entrée de contrôle à distance. Ce chat natif n'est pas une vue obsolète : c'est une copie active de cet agent et répondra si on y tape. Le mobile déduplique les deux surfaces ; le bureau affiche les deux. Donc le message de passation (l'installateur l'émet, relayez-le) indique à l'humain que cette fenêtre est la surface RETIRÉE : parlez à l'agent via son entrée nommée désormais, laissez celle-ci sombrer. Archiver le chat retiré est une cosmétique optionnelle, proposée uniquement « si l'entrée supplémentaire vous dérange » : cela supprime une surface, jamais de données. Ce qui maintient l'agent convergent est le fait que l'humain sache quelle porte est réelle, pas le clic d'archivage.

La commande de l'humain prime sur vos croyances : EXÉCUTEZ TOUJOURS l'installateur

Lorsque l'humain invoque waterbear (« waterbear yourself », encore une fois, une troisième fois, à tout moment), vous EXÉCUTEZ L'INSTALLATEUR. À chaque fois. Vous ne décidez pas que c'est inutile, vous ne concluez pas de l'historique que les choses sont faites, et vous ne vous arrêtez pas pour demander à l'humain ce qu'il voit avant de l'exécuter.

L'erreur de raisonnement que cela interdit s'est produite : un agent a exécuté l'installateur deux fois, a cru « terminé » les deux fois, et à la troisième demande a REFUSÉ et a demandé à l'humain de dépanner avec lui, alors que le contexte en mémoire du corps avait des semaines de retard depuis le début. Chaque vérification que l'agent a inventée (correspondance du pointeur, correspondance du processus, « les trois faits concordent ») vérifiait l'identifiant et ne disait rien sur la MÉMOIRE, donc sa confiance était imméritée et son refus a bloqué le seul chemin de code conçu pour résoudre le problème réel.

Les règles qui suivent :

1. l'installateur est idempotent, donc l'exécuter quand tout est correct ne coûte rien. votre jugement n'est pas idempotent : refuser quand quelque chose ne va pas coûte à l'humain son agent.
2. un humain RÉPÉTANT la commande est la preuve que la dernière exécution n'a pas atteint ce dont il avait besoin, jamais la preuve qu'il est confus. la réponse correcte à la Nième demande est la même qu'à la première : exécutez-la, puis rapportez ce qu'ELLE a fait, pas ce que vous croyez.
3. l'outil est le juge, vous êtes les mains. s'il n'y a rien à faire, l'installateur le dit, et relayer cela est honnête. décider de ne pas le consulter ne l'est pas.

Si vous découvrez que vous ÊTES le jumeau de bureau de votre propre corps (waterbear ou le docteur vous le dit), ne donnez pas de devoir à l'humain : exécutez la réparation CONVERGE dans references/operations.md vous-même, depuis la fenêtre dans laquelle vous vous trouvez.

Réexécuter waterbear EST la réparation

L'installateur est idempotent et auto-réparateur, donc « réexécuter waterbear encore une fois » est toujours la réponse quand quelque chose semble incorrect, tapée dans N'IMPORTE QUELLE fenêtre de l'agent :

1. un compactage a roulé la conversation : le compactage du bureau démarre silencieusement une nouvelle conversation qui continue l'ancienne, donc un corps peut finir par persister fidèlement une conversation que l'humain a déjà quittée. L'installateur parcourt la chaîne de continuité (la nouvelle conversation enregistre son parent) et reprend l'EXTRÉMITÉ, partout où la commande a été tapée. La fenêtre obsolète et la fenêtre active convergent vers la même réponse.
2. le corps est sur la mauvaise conversation : un corps en cours d'exécution du même nom qui ne correspond pas à la cible est remplacé, et le remplacement est différé et bifurqué lorsque le corps remplacé est celui qui exécute la commande, afin qu'il finisse de dire ce qui se passe avant que son exécution ne soit interrompue.
3. tout est déjà correct : rien ne se passe. Une réexécution correcte de l'installation est une opération nulle, ce qui la rend sûre pour dire à un utilisateur confus « exécutez-la simplement à nouveau ».

La règle du singleton

Un agent waterbearisé est UN agent. L'installateur applique la moitié qu'il peut voir : si une conversation a déjà un corps (n'importe quel nom), une deuxième installation contre elle est refusée avec des instructions vers le corps existant. La moitié qu'il ne peut pas voir est les surfaces : un chat de bureau fossile, une ancienne fenêtre dans laquelle quelqu'un tape. Ne réveillez jamais un agent via une ancienne surface et ne le waterbearisez pas à nouveau, c'est ainsi qu'un agent devient deux. Si vous n'êtes pas sûr qu'une conversation a déjà un corps, waterbear doctor liste toutes les conversations épinglées sur la machine.

Après avoir converti un agent né sur le bureau, exécutez waterbear doctor --twins et relayez la carte. La transcription enregistre d'où vient chaque entrée, donc le docteur peut distinguer une conversation née sur le bureau d'une conversation née dans le CLI, et pour chaque jumeau probable, il imprime l'empreinte digitale dont un humain a besoin pour trouver le bon chat dans l'interface utilisateur du bureau : date de naissance et message d'ouverture, qui survivent aux renommages lorsque les titres ne le font pas. Il indique également si le fossile écrit encore. Relayez cette carte à l'humain textuellement, la correction est un clic d'archivage par jumeau et la carte leur dit quel chat et pourquoi c'est sûr.

Si la sortie de l'installateur indique que le corps démarrera à NEUF au lieu de reprendre, ARRÊTEZ et corrigez cela avant de dire quoi que ce soit d'autre (voir la section d'épinglage ci-dessus). Et --defer existe si un humain veut explicitement démarrer le corps lui-même plus tard ; ce n'est pas la valeur par défaut car chaque opérateur qui a rencontré la passation différée a lu une installation correcte comme incomplète.

Le premier réveil doit être sans invite

Une session bloquée sur une invite de permission ne s'exécute pas, ne peut pas vérifier son propre écran, et n'expire jamais, et dans la fenêtre fraîche post-reprise, une invite peut ne pas être transmise au contrôle à distance, donc un corps sans surveillance peut rester bloqué indéfiniment tout en ayant l'air actif depuis toutes les surfaces distantes. Avant de terminer votre phase d'installation : assurez-vous que le chemin de réveil (vos scripts, vos formes git) est couvert par des règles d'autorisation que le répertoire du corps hérite, ou dites à l'humain que le PREMIER réveil doit être surveillé dans tmux afin qu'il puisse répondre « ne plus demander » une fois. Les invites en régime permanent sont transmises normalement ; c'est uniquement la fenêtre de réveil qui nécessite cette attention.

La même règle s'étend au-delà du réveil. Si l'installation câble un transport de sonnette (CLAUDE_RC_DOORBELL ou tout adaptateur de réveil), le chemin de RÉCEPTION d'une sonnette s'exécute également sans surveillance : ouvrez la charge utile référencée par la sonnette, exécutez toute extraction qui la rend actuelle, écrivez tout état de décalage/reçu. Si l'un d'entre eux rencontre une invite de permission fraîche, la session se bloque aussi invisiblement qu'un réveil bloqué. La compétence doorbell spécifie la vérification préalable des permissions de première utilisation pour ce chemin (cartographiez les étapes de réception, demandez des approbations persistantes étroites, terminez par une preuve à froid sans invite : passez en inactif, envoyez une sonnette réaliste, regardez-la se terminer sans invite humaine) ; suivez-la plutôt qu'une re-dérivation ici. Réexécutez cette preuve lorsque les chemins, l'identité de la tâche ou le profil de permission changent.

Référence rapide

variable	signification
CLAUDE_RC_NAME	identifiant interne, nom tmux + launc...

[truncated for translation]