waterbear은(는) 무엇을 하나요?
개요
claude --remote-control 세션을 무기한 유지합니다. 이름은 물곰(tardigrade)에서 따왔으며, 물곰은 스트레스 상황에서 생명 활동을 중단했다가 조건이 회복되면 다시 살아나는 동물입니다. 크래시, 패치, 종료 또는 재부팅으로 프로세스가 종료되면 waterbear가 자동으로 다시 살리고, (선택적으로) 디스크에서 정확히 이전 대화를 이어받아 에이전트가 생각하던 중간부터 그대로 돌아옵니다.
사용 시기
- 크래시/패치/종료/재부팅에서 살아남아 스스로 재시작하는 세션이 필요할 때
- 휴대폰/데스크톱/claude.ai 어디서든 항상 접근 가능해야 할 때 (remote-control)
- 재시작 시 이전 대화를 이어가고, 새 빈 대화가 아닌 경우
- 누군가 "이 에이전트를 항상 켜두게/영구적으로/죽지 않게/영속적으로 만들어줘"라고 말할 때
사용하지 말아야 할 때: 일회성 작업, 또는 터미널을 닫으면 종료되어도 되는 세션.
실행 환경 (먼저 읽으세요, 단일 머신에서만 동작합니다)
waterbear는 한 컴퓨터에서 launchd LaunchAgent + tmux + claude CLI 프로세스를 연결합니다. 미리 알아야 할 결과가 있습니다:
- macOS 전용 (launchd). 패턴은 Linux/systemd로 이식 가능합니다 (references/architecture.md 참조). 하지만 이 설치 프로그램은 Mac용입니다. 해당 머신과 사용자에 종속되며, LaunchAgent는 사용자별로 작동하고 로그인 중일 때만 지속됩니다. 본체는 다른 머신으로 따라가지 않습니다.
- Claude Desktop 앱: 작동합니다. 데스크톱과 CLI는 동일한 디스크 기반 대화 기록을 사용하므로, CLI 본체는 데스크톱 대화를 ID로 이어받을 수 있습니다(단, 해당 대화의 작업 디렉토리에서 실행되어야 하며, never-move 가드가 이를 강제합니다). 데스크톱 창은 이제 내구성 있는 세션의 또 다른 원격 제어 뷰가 됩니다. (이 문서의 이전 버전에서는 데스크톱 대화를 이어받을 수 없다고 주장했지만, 이는 잘못된 정보였으며 실제로 수행하여 반증되었습니다.)
- 클라우드 / 웹에서의 Claude Code: 해당 없음. 로컬 머신, launchd, tmux가 없어 유지할 수 없습니다. waterbear는 사용자 컴퓨터에서 실행되는 세션을 위한 것입니다.
- 인증 만료 시 대화형 재로그인 필요: CLI는 구독 로그인(OAuth)으로 실행되며, 주기적으로 만료됩니다. 만료되면 세션은 계속 살아 있고 각 요청 시 인증 오류를 표시하므로, 스스로 알립니다(휴대폰이나 데스크톱에서 remote-control을 통해 볼 수 있음). 조용히 죽지 않습니다. 머신에서
claude+/login을 실행하여 해결하세요. waterbear는 이 문제를 자체 복구할 수 없습니다(launchd는 브라우저 인증을 구동할 수 없음). 구독 기반에서 예상되는 동작이며 버그가 아닙니다(API 키 인증은 이를 피할 수 있지만 청구가 종량제로 전환됨). 별도로, 가드에는 크래시루프 넷(알림 + 백오프)이 있어 세션이 실제로 죽고 반복적으로 재시작되는 경우(예: 잘못된 재개 ID 또는 손상된 상태)를 처리합니다. 만료된 로그인은 이를 트리거하지 않습니다.
Mac에 항상 켜져 있는 프로세스를 원하지 않는다면 설치하지 마세요.
Waterbear yourself (일반적인 사용 사례)
대부분의 경우 에이전트가 스스로 이 작업을 실행합니다("waterbear yourself"). 이렇게 하면 이 대화가 재시작에서 살아남고 자동으로 이어집니다. 기본값이 모든 작업을 수행합니다: 현재 디렉토리, 현재 세션.
스크립트는 이 파일 옆의 scripts/ 디렉토리에 있습니다. 만약 리포지토리 URL만 전달받고 로컬에 없다면, 먼저 클론하고 스킬을 모든 future 세션에서 재사용 가능하게 만들려면 스킬 디렉토리에 직접 클론하세요:
git clone https://github.com/royashbrook/waterbear ~/.claude/skills/waterbear
그런 다음 ~/.claude/skills/waterbear/scripts/waterbear-install에서 설치 프로그램을 실행하세요. 최소 단계:
- 짧은 내부 이름(공백 없음)을 선택하세요. 보통 사용자의 이름(
max,sam)을 사용합니다.CLAUDE_RC_TITLE에는 사용자가 이미 이 대화를 부르는 이름을 사용하세요. 당신이 만든 제목이 아닙니다. 원격 제어 항목은 세션 목록에서 사용자의 채팅을 대체하며, 스스로 선택한 새 이름으로 돌아오면 다른 에이전트가 나타나고 사용자의 것이 사라진 것처럼 보입니다. 사용자가 무엇이라고 부르는지 모른다면 물어보세요. 한 번의 질문이며, 당신의 이름이 아니라 그들의 이름입니다. - 할 일 없음:
CLAUDE_RC_RESUME=1을 사용하면 설치 프로그램이 실행 중인 세션을 고정하므로 이 대화가 다시 돌아옵니다. 어떤 대화인지 출력합니다. 그 줄을 읽으세요. 본체가 새로 시작된다고 표시되면, 더 진행하기 전에 멈추고 수정하세요. 새로 시작한다는 것은 사용자가 실제 에이전트 옆에 완전히 새로운 빈 에이전트를 갖게 된다는 뜻이며, 이 도구가 만들 수 있는 최악의 결과입니다. (--no-pin은 의도적으로 자신의 ID를 가져오지 않으려는 드문 경우에 존재합니다. 사용한다면 큰 소리로 말하세요.) - 캡처 후크가 SessionStart 후크로 연결되어 있는지 확인하세요(references/architecture.md의 "The capture hook" 참조). 이렇게 하면 ID가 모든 future 재시작에서 자동 복구됩니다. 프로젝트가 이미 연결되어 있다면 건너뛰세요.
- 재개 모드로 가드를 설치하고, 현재 위치를 기본값으로 사용하세요:
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은 자체 프로젝트 디렉토리 내에서만 세션을 찾습니다. 따라서 다른 곳을 가리키는 본체는 새 대화를 시작하고, 사용자는 한 창에 실제 에이전트, 다른 창에 빈 가짜를 갖게 됩니다. 설치 프로그램은 이제 이를 거부하지만, 거부는 그물일 뿐 계획이 아닙니다. 에이전트를 이동하지 마세요.
Waterbear yourself: 인계는 자동입니다, 사실만 말하세요
자신의 세션 내에서 설치하면 즉시 내구성 있는 본체가 시작되고, 본체는 이 대화를 이어받습니다: 동일한 세션 ID, 동일한 단일 기록, 추가로 이어집니다. 사용자가 보고 있는 창은 해당 대화의 뷰이며, 원격 제어가 등록되면 따라잡습니다. 포크되지 않고, 두 번째 본체가 없으며, 사용자가 먼저 닫아야 할 것도 없습니다.
따라서 설치 후 사용자에게 세 가지 사실만 알리고, 추가 과제는 주지 마세요:
- 완료: 이 대화는 이제 내구성이 있습니다. 크래시, 패치, 종료 및 재부팅에서 살아남습니다.
- 창이 깜빡이거나 원격 제어가 재등록되는 동안 잠시 오래된 뷰를 보여줄 수 있습니다. 기본 대화는 디스크에 있는 하나의 기록이며 완전합니다. 예상보다 짧은 스크롤백은 렌더링 아티팩트일 뿐, 손실된 메모리가 아닙니다.
- 어디서든 접근 가능합니다: 휴대폰, 데스크톱 앱 또는
tmux attach -t <name>을 통해.
데스크톱에서 시작된 대화에 대한 추가 사항 (설치 프로그램이 이를 감지하고 알려줍니다). 데스크톱은 새 원격 제어 항목과 함께 대화에 대한 고유 채팅을 유지합니다. 그 고유 채팅은 오래된 뷰가 아닙니다: 이 에이전트의 살아있는 두 번째 복사본이며, 입력하면 응답합니다. 모바일은 두 표면을 중복 제거합니다. 데스크톱은 둘 다 표시합니다. 따라서 인계 메시지(설치 프로그램이 출력합니다, 전달하세요)는 사용자에게 이 창이 은퇴된 표면임을 알립니다: 지금부터는 이름이 있는 항목에서 에이전트와 대화하고, 이 창은 그대로 두세요. 은퇴된 채팅을 보관 처리하는 것은 선택적 미용이며, "추가 항목이 거슬린다면" 제공됩니다: 표면을 제거할 뿐, 데이터는 절대 제거하지 않습니다. 에이전트가 수렴되도록 유지하는 것은 사용자가 어떤 문이 진짜인지 아는 것이지, 보관 클릭이 아닙니다.
사용자의 명령이 당신의 믿음보다 우선합니다: 항상 설치 프로그램을 실행하세요
사용자가 waterbear를 호출하면 ("waterbear yourself", 다시, 세 번째, 언제든지), 설치 프로그램을 실행하세요. 매번. 불필요하다고 판단하지 말고, 기록에서 완료되었다고 결론 내리지 말며, 실행하기 전에 사용자에게 무엇이 보이는지 묻기 위해 멈추지 마세요.
이것이 금지하는 추론 오류가 이미 발생했습니다: 에이전트가 설치 프로그램을 두 번 실행하고, 두 번 모두 "완료"라고 믿었으며, 세 번째 요청에서 거부하고 사용자에게 함께 문제를 해결하자고 요청했습니다. 그동안 본체의 인-메모리 컨텍스트는 몇 주 전의 것이었습니다. 에이전트가 고안한 모든 검사(포인터 일치, 프로세스 일치, "세 가지 사실 모두 일치")는 ID를 확인했을 뿐 메모리에 대해서는 아무 것도 말하지 않았으므로, 그 확신은 근거 없었고 거부는 실제 문제를 해결하도록 만들어진 유일한 코드 경로를 차단했습니다.
다음 규칙을 따르세요:
- 설치 프로그램은 멱등적이므로 모든 것이 올바를 때 실행해도 아무 손해가 없습니다. 당신의 판단은 멱등적이지 않습니다: 무언가 잘못되었을 때 거부하면 사용자는 에이전트를 잃습니다.
- 사용자가 명령을 반복하는 것은 마지막 실행이 그들이 필요로 하는 것을 달성하지 못했다는 증거이며, 그들이 혼란스럽다는 증거가 아닙니다. N번째 요청에 대한 올바른 응답은 첫 번째와 동일합니다: 실행한 다음, 도구가 한 일을 보고하세요. 당신이 믿는 것을 보고하지 마세요.
- 도구가 판사이고, 당신은 손입니다. 할 일이 없다면 설치 프로그램이 그렇게 말하며, 그것을 전달하는 것은 정직합니다. 설치 프로그램을 참조하지 않기로 결정하는 것은 그렇지 않습니다.
당신이 자신의 본체의 데스크톱 쌍둥이임을 발견했다면 (waterbear 또는 doctor가 알려줍니다), 사용자에게 숙제를 주지 마세요: 당신이 있는 창에서 직접 references/operations.md의 CONVERGE 수리를 실행하세요.
Waterbear를 다시 실행하는 것이 수리입니다
설치 프로그램은 멱등적이고 자가 치유되므로, 무언가 잘못된 것처럼 보일 때 "waterbear를 다시 실행하세요"가 항상 답입니다. 에이전트의 모든 창에 입력하세요:
- 컴팩트가 대화를 롤링했습니다: 데스크톱 컴팩트는 조용히 이전 대화를 이어가는 새 대화를 시작하므로, 본체는 사용자가 이미 떠난 대화를 충실히 유지할 수 있습니다. 설치 프로그램은 연속 체인(새 대화는 부모를 기록함)을 따라가며 명령이 입력된 곳의 팁을 이어받습니다. 오래된 창과 살아있는 창은 동일한 답변으로 수렴합니다.
- 본체가 잘못된 대화에 있습니다: 대상과 일치하지 않는 실행 중인 동일 이름의 본체는 교체되며, 교체가 명령을 실행하는 본체인 경우 교체는 지연 + 포크되어, 본체가 바닥이 제거되기 전에 무슨 일이 일어나고 있는지 말을 마칠 수 있습니다.
- 모든 것이 이미 올바릅니다: 아무 일도 일어나지 않습니다. 올바른 설치 재실행은 no-op이며, 이것이 혼란스러운 사용자에게 "그냥 다시 실행하세요"라고 말하는 것이 안전한 이유입니다.
싱글톤 규칙
waterbear 처리된 에이전트는 하나의 에이전트입니다. 설치 프로그램은 자신이 볼 수 있는 절반을 강제합니다: 대화에 이미 본체가 있다면(어떤 이름이든), 두 번째 설치가 거부되고 기존 본체에 대한 안내가 제공됩니다. 볼 수 없는 절반은 표면입니다: 화석 데스크톱 채팅, 누군가 입력하는 오래된 창. 절대 오래된 표면을 통해 에이전트를 깨우고 다시 waterbear 처리하지 마세요. 그것이 하나의 에이전트가 둘이 되는 방법입니다. 대화에 이미 본체가 있는지 확실하지 않다면, waterbear doctor가 머신의 모든 고정된 대화를 나열합니다.
데스크톱에서 시작된 에이전트를 변환한 후, waterbear doctor --twins를 실행하고 카드를 전달하세요. 기록은 각 항목이 어디서 왔는지 저장하므로, doctor는 데스크톱에서 시작된 대화와 CLI에서 시작된 대화를 구분할 수 있으며, 각 가능한 쌍둥이에 대해 사용자가 데스크톱 UI에서 올바른 채팅을 찾는 데 필요한 지문을 출력합니다: 제목이 아닌 이름 변경에서 살아남는 생년월일과 시작 메시지. 또한 화석이 여전히 쓰기 중인지 보고합니다. 그 카드를 사용자에게 그대로 전달하세요. 수정은 쌍둥이당 하나의 보관 클릭이며, 카드는 어떤 채팅이고 왜 안전한지 알려줍니다.
설치 프로그램 출력이 본체가 재개 대신 새로 시작될 것이라고 말하면, 다른 말을 하기 전에 멈추고 수정하세요 (위의 핀 섹션 참조). 그리고 --defer는 사용자가 명시적으로 나중에 본체를 시작하려는 경우 존재합니다. 지연된 인계를 만난 모든 운영자가 올바른 설치를 불완전한 것으로 읽었기 때문에 기본값이 아닙니다.
첫 번째 웨이크는 프롬프트가 없어야 합니다
권한 프롬프트에서 차단된 세션은 실행 중이 아니며, 자체 화면을 확인할 수 없고, 타임아웃되지 않습니다. 그리고 재개 후 새 창에서 프롬프트가 원격 제어로 전달되지 않을 수 있으므로, 무인 본체는 모든 원격 표면에서 바쁘게 보이면서 영원히 차단될 수 있습니다. 설치를 끝내기 전에: 웨이크 경로(스크립트, git shapes)가 본체 디렉토리가 상속하는 허용 규칙으로 커버되는지 확인하거나, 사용자에게 첫 번째 웨이크를 tmux에서 감시하여 한 번 "다시 묻지 않음"에 답할 수 있도록 알리세요. 정상 상태 프롬프트는 정상적으로 전달됩니다. 오직 웨이크 창만 이 주의가 필요합니다.
동일한 규칙은 웨이크 이후로도 확장됩니다. 설치가 링 전송(CLAUDE_RC_DOORBELL 또는 모든 웨이크 어댑터)을 연결하는 경우, 링의 수신 경로도 무인으로 실행됩니다: 링이 참조하는 페이로드를 열고, 그것을 최신 상태로 만드는 풀을 실행하고, 오프셋/영수증 상태를 씁니다. 이들 중 하나라도 새 권한 프롬프트에 부딪히면 차단된 웨이크만큼 눈에 띄지 않게 세션을 중단시킵니다. 초인종 스킬은 해당 경로에 대한 첫 사용 권한 사전 점검을 지정합니다(수신 단계를 매핑하고, 좁은 영구 승인을 요청하며, 콜드 노 프롬프트 증명으로 마무리: 유휴 상태로 가고, 현실적인 링을 보내고, 사람 프롬프트 없이 완료되는지 감시). 여기서 재파생하지 말고 따르세요. 경로, 작업 ID 또는 권한 프로필이 변경될 때 해당 증명을 다시 실행하세요.
빠른 참조
| 환경 변수 | 의미 |
|---|---|
CLAUDE_RC_NAME | 내부 ID, tmux 이름 + launchd 레이블 |
CLAUDE_RC_DIR | 본체의 작업 디렉토리, claude --resume이 대화를 찾는 곳 |
CLAUDE_RC_RESUME | 1로 설정하면 이전 대화 재개, 설정하지 않으면 새로 시작 |
CLAUDE_RC_RESUME_WAKE | 재개 후 입력할 재초기화 큐(선택 사항) |
CLAUDE_RC_WAKE | 재개할 대화가 없을 때 사용할 아이덴티티 부트스트랩(선택 사항) |
CLAUDE_RC_TITLE | remote-control 목록에 표시될 이름, 사용자가 부르는 이름 사용 |
CLAUDE_RC_DOORBELL | 링 전송 경로(선택 사항) |
CLAUDE_RC_NO_PIN | 1로 설정하면 현재 세션 고정 안 함(드문 경우) |
참조
- architecture.md - 아키텍처, 캡처 후크, 동작 원리
- operations.md - 수리, 트윈 감지, 운영 절차
- 초인종 스킬 - 링 전송 통합