royashbrook/waterbear

¿Qué hace waterbear?

Resumen

Mantén una sesión de claude --remote-control viva indefinidamente. Nombrado en honor al tardígrado, el animal que suspende su vida bajo estrés y revive cuando las condiciones vuelven. Una caída, un parche, un cierre o un reinicio mata el proceso; waterbear lo trae de vuelta por sí mismo y (opcionalmente) reanuda la conversación anterior desde el disco, para que el agente regrese como él mismo, a mitad de un pensamiento.

Cuándo usarlo

• Quieres una sesión que sobreviva a caídas / parches / cierres / reinicios y se reinicie sola.
• Quieres que sea accesible desde el teléfono / escritorio / claude.ai en todo momento (control remoto).
• Quieres que al reiniciar se REANUDE la conversación anterior, no una en blanco nueva.
• Alguien dice "haz que este agente esté siempre activo / sea persistente / inmatable / permanente".

No es para: una tarea puntual o una sesión que QUIERES que termine al cerrar la terminal.

Dónde se ejecuta (lee primero, es local a una máquina)

Waterbear conecta un LaunchAgent de launchd + tmux + un proceso CLI de claude en UN SOLO ordenador. Esto tiene consecuencias que vale la pena mencionar de antemano:

• Solo macOS (launchd). El patrón se puede portar a Linux/systemd (ver references/architecture.md), pero este instalador es para Mac. Está vinculado a esa máquina y usuario; el LaunchAgent es por usuario y es duradero solo mientras estés conectado, y el cuerpo no te sigue a otra máquina.
• App de Claude Desktop: funciona. El escritorio y la CLI escriben las mismas transcripciones en disco, por lo que el cuerpo de la CLI PUEDE reanudar una conversación de escritorio por ID, siempre que se inicie en el directorio de trabajo de la conversación (la regla de no mover lo garantiza). La ventana del escritorio se convierte en una vista más de control remoto de la sesión ahora duradera. (Una versión anterior de este documento afirmaba que las conversaciones de escritorio no se podían reanudar; eso era incorrecto y se demostró al hacerlo).
• Nube / Claude Code en la web: no aplica, no hay una máquina local, launchd o tmux que mantener vivo. Waterbear es para una sesión que se ejecuta en tu propio ordenador.
• La caducidad de autenticación requiere un inicio de sesión interactivo: la CLI se ejecuta con tu inicio de sesión de suscripción (OAuth), que caduca periódicamente. Cuando esto sucede, la sesión SE MANTIENE VIVA y muestra un error de autenticación en cada solicitud, por lo que se anuncia a sí misma (la ves a través del control remoto en tu teléfono o escritorio), NO muere en silencio. Ejecuta claude + /login en la máquina para solucionarlo. Waterbear no puede autoreparar esto (launchd no puede impulsar una autenticación de navegador), y es esperado con una infraestructura de suscripción, no un error (la autenticación con clave API lo evitaría, pero cambiaría la facturación a medida). Por separado, el guardián tiene una red de bucle de caídas (notificar y retroceder) para una sesión que realmente muere y se reinicia en un bucle, por ejemplo, un ID de reanudación incorrecto o un estado corrupto; un inicio de sesión caducado no lo activa.

Si no deseas un proceso siempre activo vinculado a tu Mac, no lo instales.

Waterbear tú mismo (el caso común)

La mayoría de las veces, un agente ejecuta esto SOBRE SÍ MISMO, "waterbear yourself", para hacer que ESTA conversación sobreviva a reinicios y se reanude automáticamente. Los valores predeterminados hacen el trabajo: tu directorio actual, tu sesión actual.

Los scripts se encuentran en scripts/ junto a este archivo. Si solo te dieron la URL del repositorio y aún no lo tienes localmente, clónalo primero, y para que la habilidad sea reutilizable en cada sesión futura, clónalo directamente en el directorio de habilidades:

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

Luego ejecuta el instalador en ~/.claude/skills/waterbear/scripts/waterbear-install. Pasos mínimos:

1. Elige un nombre interno corto (sin espacios), generalmente el tuyo propio (max, sam). Para CLAUDE_RC_TITLE, usa el nombre que el humano ya usa para esta conversación, su palabra para ella, no un título que inventes. La entrada de control remoto reemplaza su chat en la lista de sesiones, y volver bajo un nombre nuevo elegido por uno mismo se lee como un agente diferente que aparece y el suyo desaparece. Si no sabes cómo la llaman, pregúntalo, es una pregunta y es su nombre, no el tuyo.
2. No hay nada que hacer: con CLAUDE_RC_RESUME=1, el instalador fija la sesión desde la que lo ejecutas, por lo que ESTA conversación es la que regresa. Imprime qué conversación es. Lee esa línea. Si dice que el cuerpo comenzará FRESCO, detente y arréglalo antes de continuar, porque un inicio fresco significa que el humano termina con un agente vacío y nuevo al lado de su agente real, que es el peor resultado que esta herramienta puede producir. (--no-pin existe para el caso raro en que deliberadamente no quieras llevar tu propio ID; si lo usas, dilo en voz alta).
3. Asegúrate de que el gancho de captura esté conectado como un gancho SessionStart (consulta "El gancho de captura" en references/architecture.md) para que el ID se autorepare en cada reinicio futuro. Si tu proyecto ya lo conecta, omite esto.
4. Instala el guardián en modo de reanudación, con valores predeterminados donde estás:

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

   Opcional: CLAUDE_RC_RESUME_WAKE="<señal corta de reinicio>" (escrito después de cada reanudación, por ejemplo, para reactivar un monitor/observador) y CLAUDE_RC_WAKE="<arranque de identidad>" (usado solo si no hay ninguna conversación que reanudar).
5. Entra en el cuerpo duradero. Vive en tmux bajo launchd. ¿Ya estás dentro de una sesión de tmux llamada <nombre>? ahora eres duradero, no hay nada más que hacer. ¿No estás en tmux? la instalación inicia tu cuerpo tmux duradero, finaliza esta sesión para que las dos no se ejecuten en paralelo, y continúas en el cuerpo tmux reanudando esta misma conversación.

Solo pregunta al humano si quiere anular un valor predeterminado (un directorio diferente, avisos de activación personalizados). De lo contrario, simplemente configúrate y confirma.

No muevas al agente

CLAUDE_RC_DIR es donde el agente se está ejecutando realmente ahora mismo, y el valor predeterminado (tu directorio actual) casi siempre es correcto. No lo configures donde sientas que el agente "pertenece", ni en un directorio de proyecto, ni en un árbol de trabajo que consideres su base. Esas son tus ideas sobre el agente; el directorio es un hecho sobre él.

El fallo es silencioso y total: claude --resume solo encuentra una sesión dentro de su propio directorio de proyecto, por lo que un cuerpo apuntado a otro lugar comienza una conversación FRESCA, y el humano se queda con su agente real en una ventana y un impostor vacío en otra. El instalador ahora rechaza esto, pero el rechazo es una red, no un plan. Simplemente no muevas al agente.

Waterbear tú mismo: la toma de control es automática, di solo lo que es cierto

Instalar desde tu propia sesión inicia el cuerpo duradero inmediatamente, y el cuerpo REANUDA ESTA conversación: el mismo ID de sesión, la misma transcripción única, añadiendo contenido. La ventana que el humano está mirando es una VISTA de esa conversación, y se pone al día cuando el control remoto se registra. No hay bifurcación, no hay un segundo cuerpo, y no hay nada que el humano deba cerrar primero.

Entonces, después de instalar, dile al humano tres cosas ciertas, y ninguna tarea:

1. hecho: esta conversación ahora es duradera, sobrevive a caídas, parches, cierres y reinicios
2. la ventana puede parpadear o mostrar brevemente una vista obsoleta mientras el control remoto se vuelve a registrar; la conversación subyacente es una transcripción en disco y está completa, y un desplazamiento hacia atrás más corto de lo esperado es un artefacto de representación, no memoria perdida
3. pueden alcanzarla desde cualquier lugar: su teléfono, la aplicación de escritorio o tmux attach -t <nombre>

Una adición para conversaciones nacidas en el escritorio (el instalador lo detecta y lo dice). El escritorio mantiene su chat NATIVO para la conversación junto a la nueva entrada de control remoto. Ese chat nativo no es una vista obsoleta: es una segunda copia viva de este agente y responderá si se escribe en él. El móvil desduplica las dos superficies; el escritorio muestra ambas. Por lo tanto, el mensaje de entrega (el instalador lo emite, transmítelo) le dice al humano que esta ventana es la superficie RETIRADA: habla con el agente en su entrada con nombre de ahora en adelante, deja que esta se hunda. Archivar el chat retirado es cosmético opcional, ofrecido solo "si la entrada extra te molesta": elimina una superficie, nunca datos. Lo que mantiene al agente convergido es que el humano sepa qué puerta es real, no el clic de archivo.

El comando del humano supera tus creencias: SIEMPRE ejecuta el instalador

Cuando el humano invoca waterbear ("waterbear yourself", de nuevo, una tercera vez, en cualquier momento), EJECUTAS EL INSTALADOR. Cada vez. No decides que no es necesario, no concluyes del historial que las cosas están hechas, y no te detienes a preguntarle al humano qué está viendo antes de ejecutarlo.

El error de razonamiento que esto prohíbe ha ocurrido: un agente ejecutó el instalador dos veces, creyó "hecho" ambas veces, y en la tercera petición SE NEGÓ y le pidió al humano que solucionara el problema con él, mientras que el contexto en memoria del cuerpo estaba semanas atrasado todo el tiempo. Cada verificación que el agente inventó (coincidencia de puntero, coincidencia de proceso, "los tres hechos concuerdan") verificó el ID y no dijo nada sobre la MEMORIA, por lo que su confianza era inmerecida y su negativa bloqueó la única ruta de código diseñada para solucionar el problema real.

Las reglas que siguen:

1. el instalador es idempotente, por lo que ejecutarlo cuando todo está bien no cuesta nada. tu juicio no es idempotente: negarse cuando algo está mal le cuesta al humano su agente.
2. un humano que REPITE el comando es evidencia de que la última ejecución no logró lo que necesitaban, nunca evidencia de que están confundidos. la respuesta correcta a la enésima petición es la misma que a la primera: ejecútala, luego informa lo que HIZO, no lo que tú crees.
3. la herramienta es el juez, tú eres las manos. si no hay nada que hacer, el instalador lo dice, y transmitir eso es honesto. decidir no consultarla no lo es.

Si descubres que ERES el gemelo de escritorio de tu propio cuerpo (waterbear o el médico te lo dice), no le des tarea al humano: ejecuta tú mismo la reparación CONVERGE en references/operations.md, desde la ventana en la que estás.

Volver a ejecutar waterbear ES la reparación

El instalador es idempotente y se autorepara, por lo que "vuelve a ejecutar waterbear" es siempre la respuesta cuando algo parece mal, escrito en CUALQUIERA de las ventanas del agente:

1. un compactado desplazó la conversación: el escritorio compacta iniciando silenciosamente una nueva conversación que continúa la anterior, por lo que un cuerpo puede terminar persistiendo fielmente una conversación que el humano ya dejó. El instalador recorre la cadena de continuación (la nueva conversación registra su padre) y reanuda la PUNTA, dondequiera que se haya escrito el comando. La ventana obsoleta y la ventana viva convergen en la misma respuesta.
2. el cuerpo está en la conversación equivocada: un cuerpo activo con el mismo nombre que no coincide con el objetivo es reemplazado, y el reemplazo se aplaza y se bifurca cuando el cuerpo que se reemplaza es el que ejecuta el comando, para que termine de decir lo que está sucediendo antes de que se retire su suelo.
3. todo ya está correcto: no pasa nada. Una reinstalación correcta es una operación sin efecto, lo que la hace segura para decirle a un usuario confundido "solo ejecútalo de nuevo".

La regla de singleton

Un agente waterbear es UN agente. El instalador aplica la mitad que puede ver: si una conversación ya tiene un cuerpo (cualquier nombre), una segunda instalación en ella se rechaza con instrucciones hacia el cuerpo existente. La mitad que no puede ver son las superficies: un chat de escritorio fósil, una ventana antigua en la que alguien escribe. Nunca despiertes a un agente a través de una superficie antigua y lo vuelvas a waterbear, así es como un agente se convierte en dos. Si no estás seguro de si una conversación ya tiene un cuerpo, waterbear doctor lista cada conversación fijada en la máquina.

Después de convertir un agente nacido en el escritorio, ejecuta waterbear doctor --twins y transmite la tarjeta. La transcripción registra de dónde vino cada entrada, por lo que el doctor puede distinguir una conversación nacida en el escritorio de una nacida en la CLI, y para cada posible gemelo imprime la huella digital que un humano necesita para encontrar el chat correcto en la interfaz de usuario del escritorio: fecha de nacimiento y mensaje de apertura, que sobreviven a los cambios de nombre cuando los títulos no lo hacen. También informa si el fósil sigue escribiendo. Transmite esa tarjeta al humano textualmente, la solución es un clic de archivo por gemelo y la tarjeta les dice qué chat y por qué es seguro.

Si la salida del instalador dice que el cuerpo comenzará FRESCO en lugar de reanudar, DETENTE y arréglalo antes de decir cualquier otra cosa (consulta la sección de fijación anterior). Y --defer existe si un humano quiere explícitamente iniciar el cuerpo más tarde; no es el valor predeterminado porque cada operador que encontró la entrega diferida leyó una instalación correcta como incompleta.

El primer despertar debe ser sin avisos

Una sesión bloqueada en un aviso de permiso no se está ejecutando, no puede verificar su propia pantalla y nunca agota el tiempo de espera, y en la ventana fresca posterior a la reanudación, un aviso puede no reenviarse al control remoto, por lo que un cuerpo desatendido puede permanecer bloqueado para siempre mientras parece ocupado desde todas las superficies remotas. Antes de finalizar tu turno de instalación: asegúrate de que la ruta de activación (tus scripts, tus formas de git) esté cubierta por reglas de permiso que el directorio del cuerpo hereda, o dile al humano que el PRIMER despertar debe ser vigilado en tmux para que puedan responder "no preguntar de nuevo" una vez. Los avisos en estado estable se reenvían normalmente; solo es la ventana de activación la que necesita este cuidado.

La misma regla se extiende más allá de la activación. Si la instalación conecta un transporte de timbre (CLAUDE_RC_DOORBELL o cualquier adaptador de activación), la ruta de RECEPCIÓN de un timbre también se ejecuta sin supervisión: abre la carga útil a la que hace referencia el timbre, ejecuta cualquier extracción que la haga actual y escribe cualquier estado de compensación/recibo. Cualquiera de estos que encuentre un aviso de permiso nuevo detiene la sesión tan invisiblemente como una activación bloqueada. La habilidad doorbell especifica la verificación previa de permiso de primer uso para esa ruta (mapea los pasos de recepción, solicita aprobaciones persistentes estrechas, finaliza con una prueba fría sin avisos: pasa a inactivo, envía un timbre realista, observa que se completa sin aviso humano); síguela en lugar de una rededucción aquí. Vuelve a ejecutar esa prueba cuando las rutas, la identidad de la tarea o el perfil de permiso cambien.

Referencia rápida

variable	significado
CLAUDE_RC_NAME	ID interno, nombre de tmux + launchd y clave de comunicación
CLAUDE_RC_DIR	directorio de trabajo del cuerpo (nunca muevas esto)
CLAUDE_RC_RESUME	1 para reanudar la conversación desde el disco
CLAUDE_RC_RESUME_WAKE	señal de reactivación corta después de cada reanudación
CLAUDE_RC_WAKE	arranque de identidad (primera vez o sin reanudación)
CLAUDE_RC_TITLE	nombre visible para control remoto (el del humano, no el tuyo)
CLAUDE_RC_DOORBELL	adaptador de timbre (opcional)

Referencias

• references/architecture.md — diseño, gancho de captura, patrón systemd
• references/operations.md — reparaciones, waterbear doctor, operaciones de gemelos y convergencia
• doorbell skill — timbre y rutas de activación