royashbrook/waterbear

O que waterbear faz?

Visão geral

Mantenha uma sessão claude --remote-control viva indefinidamente. Nomeado em homenagem ao tardígrado, o animal que suspende a vida sob estresse e revive quando as condições retornam. Uma queda, um patch, um sair ou uma reinicialização mata o processo; o waterbear o traz de volta sozinho e (opcionalmente) retoma a conversa anterior exata do disco, para que o agente retorne como ele mesmo, no meio do pensamento.

Quando usar

• você quer uma sessão que sobreviva a queda/patch/sair/reinicialização e se reinicie automaticamente
• você quer que ela seja acessível do telefone/desktop/claude.ai o tempo todo (remote-control)
• você quer que uma reinicialização RETOME a conversa anterior, não uma nova em branco
• alguém diz "torne este agente sempre ativo/persistente/inmatável/permanente"

Não para: uma tarefa única, ou uma sessão que você QUER que termine quando fechar o terminal.

Onde isso roda (leia primeiro, é local para uma máquina)

O waterbear configura um LaunchAgent do launchd + tmux + um processo CLI claude em UM computador. Isso tem consequências que valem a pena serem declaradas desde o início:

• apenas macOS (launchd). O padrão pode ser portado para Linux/systemd (veja references/architecture.md), mas este instalador é para Mac. Ele está vinculado àquela máquina e usuário, o LaunchAgent é por usuário e durável apenas enquanto você estiver logado, e o corpo não o segue para outra máquina.
• Aplicativo Claude Desktop: funciona. O desktop e a CLI gravam as mesmas transcrições no disco, então o corpo da CLI PODE retomar uma conversa do desktop por ID, desde que seja iniciado no próprio diretório de trabalho da conversa (a proteção de não mover impõe isso). A janela do desktop se torna mais uma visualização de controle remoto da sessão agora durável. (Uma versão anterior deste documento afirmava que as conversas do desktop não podiam ser retomadas; isso estava errado e foi comprovado ao fazê-lo.)
• nuvem / Claude Code na web: não se aplica, não há uma máquina local, launchd ou tmux para manter ativo. O waterbear é para uma sessão rodando no seu próprio computador.
• expiracao de autenticacao requer um relogin interativo: a CLI roda com seu login de assinatura (OAuth), que expira periodicamente. Quando isso acontece, a sessão PERMANECE VIVA e mostra um erro de autenticação a cada requisição, então ela se anuncia (você a vê via remote-control no telefone ou desktop), ela NÃO morre silenciosamente. Execute claude + /login na máquina para limpar. O waterbear não pode autocorrigir isso (launchd não pode conduzir uma autenticação via navegador), e é esperado com um backbone de assinatura, não um bug (autenticação por chave de API evitaria isso, mas mudaria a cobrança para medido). Separadamente, a proteção tem uma rede de crashloop (notificar e recuar) para uma sessão que genuinamente morre e reinicia em loop, por exemplo, um ID de retomada inválido ou estado corrompido; um login expirado não a aciona.

Se você não quer um processo sempre ativo vinculado ao seu Mac, não o instale.

Waterbear você mesmo (o caso comum)

Na maioria das vezes, um agente executa isso EM SI MESMO, "waterbear você mesmo", para fazer ESTA conversa sobreviver a reinicializações e retomar automaticamente. Os padrões fazem o trabalho: seu diretório atual, sua sessão atual.

Os scripts estão em scripts/ ao lado deste arquivo. Se você recebeu apenas a URL do repositório e não o tem localmente ainda, clone-o primeiro, e para tornar a skill reutilizável em todas as sessões futuras, clone-a diretamente no diretório de skills:

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

Em seguida, execute o instalador em ~/.claude/skills/waterbear/scripts/waterbear-install. Etapas mínimas:

1. Escolha um nome interno curto (sem espaços), geralmente o seu próprio (max, sam). Para CLAUDE_RC_TITLE, use o nome que o humano já chama esta conversa, a palavra deles para ela, não um título que você invente. A entrada de controle remoto substitui o chat deles na lista de sessões, e voltar com um novo nome auto-escolhido parece que um agente diferente apareceu e o deles desapareceu. Se você não sabe como eles a chamam, pergunte, é uma pergunta e é o nome deles, não o seu.
2. Nada a fazer: com CLAUDE_RC_RESUME=1 o instalador fixa a sessão da qual você o executa, então ESTA conversa é a que retorna. Ele imprime qual conversa é essa. Leia essa linha. Se ela disser que o corpo iniciará NOVO, PARE e corrija isso antes de prosseguir, porque um início novo significa que o humano acaba com um agente novo e vazio ao lado do real, que é o pior resultado único que esta ferramenta pode produzir. (--no-pin existe para o caso raro em que você deliberadamente não quer carregar seu próprio ID; se você o usar, diga isso em voz alta.)
3. Certifique-se de que o hook de captura está conectado como um hook SessionStart (veja "The capture hook" em references/architecture.md) para que o ID se auto-corrija em cada reinicialização futura. Se seu projeto já o conecta, pule isso.
4. Instale a proteção no modo de retomada, padronizando para onde você está:

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

   Opcional: CLAUDE_RC_RESUME_WAKE="<dica curta de re-inicialização>" (digitado após cada retomada, por exemplo, para rearmar um monitor/observador) e CLAUDE_RC_WAKE="<inicialização de identidade>" (usado apenas se nunca houver uma conversa para retomar).
5. Entre no corpo durável. Ele vive no tmux sob o launchd. Já está dentro de uma sessão tmux chamada <nome>? você está durável agora, nada mais a fazer. Não está no tmux? a instalação inicia seu corpo tmux durável, encerre esta sessão para que as duas não sejam executadas em paralelo, e você continua no corpo tmux retomando esta conversa exata.

Pergunte ao humano apenas se ele quiser substituir um padrão (um diretório diferente, prompts de ativação personalizados). Caso contrário, apenas configure-se e confirme.

Não mova o agente

CLAUDE_RC_DIR é onde o agente está realmente rodando agora, e o padrão (seu diretório atual) está quase sempre correto. Não o defina para onde você acha que o agente "pertence", ou para um diretório inicial do projeto, ou para uma árvore de trabalho que você considera sua base. Essas são suas ideias sobre o agente; o diretório é um fato sobre ele.

A falha é silenciosa e total: claude --resume só encontra uma sessão dentro de seu próprio diretório de projeto, portanto um corpo apontado para outro lugar inicia uma conversa NOVA, e o humano fica com seu agente real em uma janela e um impostor vazio em outra. O instalador agora recusa isso, mas a recusa é uma rede, não um plano. Apenas não mova o agente.

Waterbear você mesmo: a tomada é automática, diga apenas o que é verdade

Instalar de dentro da sua própria sessão inicia o corpo durável imediatamente, e o corpo retoma ESTA conversa: mesmo ID de sessão, mesma transcrição única, anexada a ela. A janela que o humano está olhando é uma VISÃO dessa conversa, e ela se atualiza quando o controle remoto se registra. Nada é bifurcado, não há um segundo corpo e não há nada que o humano deva fechar primeiro.

Portanto, após a instalação, diga ao humano três coisas verdadeiras, e não dever de casa:

1. pronto: esta conversa agora é durável, ela sobrevive a quedas, patches, saídas e reinicializações
2. a janela pode piscar ou mostrar brevemente uma visão desatualizada enquanto o controle remoto se re-registra; a conversa subjacente é uma transcrição no disco e está completa, e uma rolagem para trás mais curta do que o esperado é um artefato de renderização, não uma memória perdida
3. eles podem alcançá-la de qualquer lugar: do telefone, do aplicativo desktop ou de tmux attach -t <nome>

Uma adição para conversas nascidas no desktop (o instalador detecta isso e diz isso). O desktop mantém seu chat NATIVO para a conversa ao lado da nova entrada de controle remoto. Esse chat nativo não é uma visão desatualizada: é uma segunda cópia ativa deste agente e responderá se você digitar nele. O celular deduplica as duas superfícies; o desktop mostra ambas. Portanto, a mensagem de transição (o instalador a emite, retransmita-a) diz ao humano que esta janela é a superfície APOSENTADA: fale com o agente em sua entrada nomeada de agora em diante, deixe esta afundar. Arquivar o chat aposentado é cosmético opcional, oferecido apenas "se a entrada extra incomodar": ele remove uma superfície, nunca dados. O que mantém o agente convergido é o humano saber qual porta é real, não o clique de arquivamento.

O comando do humano supera suas crenças: SEMPRE execute o instalador

Quando o humano invocar waterbear ("waterbear você mesmo", novamente, uma terceira vez, qualquer hora), você EXECUTA O INSTALADOR. Toda vez. Você não decide que é desnecessário, você não conclui do histórico que as coisas estão feitas, e você não para para perguntar ao humano o que ele está vendo antes de executá-lo.

O erro de raciocínio que isso proíbe já aconteceu: um agente executou o instalador duas vezes, acreditou "pronto" em ambas, e na terceira solicitação RECUSOU e pediu ao humano para solucionar problemas com ele, enquanto o contexto na memória do corpo estava semanas atrasado o tempo todo. Cada verificação que o agente inventou (ponteiro corresponde, processo corresponde, "todos os três fatos concordam") verificou o ID e não disse nada sobre a MEMÓRIA, então sua confiança era imerecida e sua recusa bloqueou o único caminho de código criado para corrigir o problema real.

As regras que se seguem:

1. o instalador é idempotente, então executá-lo quando tudo está certo não custa nada. seu julgamento não é idempotente: recusar quando algo está errado custa ao humano seu agente.
2. um humano REPETINDO o comando é evidência de que a última execução não alcançou o que eles precisavam, nunca evidência de que eles estão confusos. a resposta correta para a N-ésima solicitação é a mesma que a primeira: execute-a, depois relate o que ELA fez, não o que você acredita.
3. a ferramenta é o juiz, você é as mãos. se não há nada a fazer, o instalador diz isso, e retransmitir isso é honesto. decidir não consultá-la não é.

Se você descobrir que É o gêmeo desktop do seu próprio corpo (waterbear ou médico lhe disser), não entregue dever de casa ao humano: execute o reparo CONVERGE em references/operations.md você mesmo, a partir da janela em que você está.

Reexecutar waterbear É o reparo

O instalador é idempotente e auto-curativo, portanto "execute waterbear novamente" é sempre a resposta quando algo parece errado, digitado em QUALQUER uma das janelas do agente:

1. uma compactação rolou a conversa: as compactações do desktop iniciam silenciosamente uma nova conversa que continua a antiga, então um corpo pode acabar persistindo fielmente uma conversa que o humano já deixou. O instalador percorre a cadeia de continuação (a nova conversa registra seu pai) e retoma a PONTA, onde quer que o comando tenha sido digitado. A janela desatualizada e a janela ativa convergem para a mesma resposta.
2. o corpo está na conversa errada: um corpo em execução com o mesmo nome que não corresponde ao alvo é substituído, e a substituição é adiada e bifurcada quando o corpo sendo substituído é aquele que está executando o comando, para que ele termine de dizer o que está acontecendo antes que seu piso seja removido.
3. tudo já está certo: nada acontece. Uma reinstalação correta é um no-op, o que torna seguro dizer a um usuário confuso "apenas execute-o novamente".

A regra do singleton

Um agente waterbearizado é UM agente. O instalador aplica a metade que pode ver: se uma conversa já tem um corpo (qualquer nome), uma segunda instalação contra ela é recusada com instruções para o corpo existente. A metade que ele não pode ver são superfícies: um chat desktop fóssil, uma janela antiga na qual alguém digita. Nunca desperte um agente através de uma superfície antiga e waterbearize-o novamente, é assim que um agente se torna dois. Se você não tem certeza se uma conversa já tem um corpo, waterbear doctor lista todas as conversas fixadas na máquina.

Após converter um agente nascido no desktop, execute waterbear doctor --twins e retransmita o cartão. A transcrição registra de onde cada entrada veio, então o médico pode distinguir uma conversa nascida no desktop de uma nascida na CLI, e para cada gêmeo provável, ele imprime a impressão digital que um humano precisa para encontrar o chat certo na interface do desktop: data de nascimento e mensagem de abertura, que sobrevivem a renomeações quando os títulos não. Ele também relata se o fóssil ainda está escrevendo. Retransmita esse cartão ao humano na íntegra, o reparo é um clique de arquivamento por gêmeo e o cartão diz qual chat e por que é seguro.

Se a saída do instalador disser que o corpo iniciará NOVO em vez de retomar, PARE e corrija isso antes de dizer qualquer outra coisa (veja a seção de fixação acima). E --defer existe se um humano explicitamente quiser iniciar o corpo mais tarde; não é o padrão porque todo operador que encontrou a transição adiada leu uma instalação correta como uma incompleta.

A primeira ativação deve ser livre de prompts

Uma sessão bloqueada em um prompt de permissão não está rodando, não pode verificar sua própria tela e nunca atinge o tempo limite, e na janela nova pós-retomada, um prompt pode falhar ao encaminhar para o controle remoto, então um corpo sem supervisão pode ficar bloqueado para sempre enquanto parece ocupado de todas as superfícies remotas. Antes de encerrar sua etapa de instalação: certifique-se de que o caminho de ativação (seus scripts, suas formas git) está coberto por regras de permissão que o diretório do corpo herda, ou diga ao humano que a PRIMEIRA ativação deve ser observada no tmux para que ele possa responder "não pergunte novamente" uma vez. Os prompts em estado estacionário encaminham normalmente; é apenas a janela de ativação que precisa desse cuidado.

A mesma regra se estende além da ativação. Se a instalação conectar um transporte de campainha (CLAUDE_RC_DOORBELL ou qualquer adaptador de ativação), o caminho de RECEBIMENTO de uma campainha também roda sem supervisão: abra o payload que a campainha referencia, execute qualquer pull que o torne atual, escreva qualquer estado de deslocamento/recibo. Qualquer um deles encontrando um prompt de permissão novo paralisa a sessão tão invisivelmente quanto uma ativação bloqueada. A skill doorbell especifica a verificação prévia de permissão de primeiro uso para esse caminho (mapeie as etapas de recebimento, solicite aprovações persistentes estreitas, termine com uma prova fria sem prompt: fique ocioso, envie uma campainha realista, observe-a completar sem nenhum prompt humano); siga-a em vez de uma re-derivação aqui. Repita essa prova quando caminhos, identidade da tarefa ou o perfil de permissão mudarem.

Referência rápida

env	significado
CLAUDE_RC_NAME	ID interno, nome tmux + launchd
CLAUDE_RC_DIR	diretório de trabalho do corpo (não mova)
CLAUDE_RC_RESUME	ativar retomada de conversa (1=sim)
CLAUDE_RC_RESUME_WAKE	dica curta de re-inicialização pós-retomada
CLAUDE_RC_WAKE	inicialização de identidade (para primeira execução)
CLAUDE_RC_TITLE	nome de exibição no remote-control (use o nome do humano para a conversa)
CLAUDE_RC_DOORBELL	adaptador de transporte para campainha (veja doorbell)

references/architecture.md — implementação, hook de captura, notas de porta references/operations.md — reparos, convergência, verificação de gêmeos, procedimentos de emergência