cc-continuity
Claude Code를 위한 제로터치(Zero-touch) 세션 로테이션 및 감독.
존재 이유. 컨텍스트 창이 가득 차면 긴 세션은 종료됩니다. 그리고 로컬 LLM들은 상황을 악화시킵니다: 그들의 창은 고정되어 있고 작으며, 내장된 압축 기능(/<compact>, 자동 압축)은 손실성(lossy) 일회성 요약입니다. 작은 모델의 경우 결정 사항, 거부된 접근 방식, 정확한 중단 지점을 조용히 누락시키며, 모든 압축 과정은 요약을 요약하므로 드리프트(drift)가 축적됩니다. cc-continuity는 창 안에서 긴 작업 공간이 숨 쉴 수 있도록 존재합니다: 안전 임계값에 도달하면 손실성 요약 대신 구조화되고 검증된 핸드오프(handoff)로 세션을 로테이션합니다.
목표는 에이전트가 인간의 개입이 정말 필요한 경우에만 관여하도록 계획된 프로젝트를 처음부터 끝까지(0에서 완료까지) 주도하게 하는 것입니다. 이 저장소는 개념 증명(proof of concept)입니다: cc-continuity 자체로 개발되었으며, 전체 개발 기록은 이 git log에 있습니다.
cc-continuity는 컨텍스트 비율을 감시하며, 임계값을 넘어서면 사용자 액션 없이 세션을 로테이션합니다:
- 에이전트가 현재 단계를 완료하고,
- cc-continuity가 검증된 핸드오프를 작성하도록 합니다,
- git 트리가 비침습적으로 스냅샷됩니다 (
refs/continuity/* refs: no commits, no tags, no branches touched),
- 컨텍스트가 지워지고 세션이 이름 변경되며,
- 연속 프롬프트(continuation prompt)가 주입되고 후속 세션은
Continuing from cp-<NNN> (<slug>-<NNN+1>).로 시작합니다.
선택적 watchdog 데몬은 모델 서버(예: 로컬 vLLM 박스)가 다운되거나 멈출 때 장기간의 무인 실행을 복구 가능하게 유지하며, 선택적 ntfy 푸시는 휴대폰에서 모니터링할 수 있게 해줍니다.
새로운 기능
가장 최근의 5가지 업데이트를 최신순으로 보여줍니다. 각 줄은 해당 커밋에 연결되어 있어 로그를 깊이 파고들지 않고도 무엇이 최근 변경되었는지 확인할 수 있습니다:
- 2026-11-06 — 핸드오프(Handoffs)는 세션 기록을 읽기 쉬운 HTML 페이지(검색, 테마 토글 기능 포함)와 원본 JSONL 형식으로 내보내며, 후속 세션에서는 네비게이터 패널에 클릭 가능한
Transcript: 링크를 표시합니다 (issue #8).
- 2026-11-05 — 알림 푸시(Notification pushes)가 더욱 풍부해졌습니다: 프로젝트, 호스트, 모델 및 컨텍스트 비율 외에도 세션의 목표, 다음 단계, 그리고 에이전트가 마지막으로 말한 내용까지 포함하며, 전송 과정에서 민감 정보는 제거됩니다 (issue #7).
- 2026-11-05 — 회전된 세션(rotated session)의 첫 번째 출력은 이제 핸드오프에서 렌더링되는 '완료/다음(Done/Next)' 네비게이터 패널이 됩니다. 따라서 작업이 어디서 재개되었는지 항상 확인할 수 있습니다 (issue #6).
- 2026-11-03 — 회전 재개 보장(Rotation resume guarantee): 로테이터는 두 번의 무작위 시도 후 포기하는 대신, 후속 세션이 실제로 재개될 때까지 반복합니다 (확인 응답 기반 키 입력). (commit).
- 2026-11-03 — 세션 인덱스 안정성(Session index stability): 정체된 회전 후 재시작 시, 새로운 세션 인덱스를 생성하는 대신 고아화된 후속 세션과 그 번호를 재사용합니다 (commit).
작동 방식(How it works)
자동 세션 루프, 선택적 워치독(watchdog), 그리고 옵트인 알림까지 전체 흐름을 한 장의 그림으로 보여줍니다:
<img src="https://raw.githubusercontent.com/pqant/claude-continuity/HEAD/docs/diagrams/flow.light.anime.en.gif#gh-light-mode-only" width="800" alt="cc-continuity flow">
<img src="https://raw.githubusercontent.com/pqant/claude-continuity/HEAD/docs/diagrams/flow.dark.anime.en.gif#gh-dark-mode-only" width="800" alt="cc-continuity flow">
데모(Demo)
전체 녹화 실행: install → 다섯 개의 연결된 세션 → 네 번의 컨텍스트 회전 → 완료된 작업까지, 처음부터 끝까지 포착한 전체 과정입니다. 이 GIF는 길이가 길기 때문에 페이지에 임베드되기보다는 다운로드 형태로 제공됩니다:
데모 자체는 다음을 통해 녹화되었습니다:
tools/demo_gif.sh (이는 ANTHROPIC_* 환경 변수에 로컬 모델 엔드포인트를 필요로 합니다); 녹화된 내용을 GIF로 변환한 컷 목록과 파이프라인은 tools/demo_segments.txt와 tools/gif_from_video.sh에 있습니다.
요구 사항 (Requirements)
- macOS 또는 WSL을 사용한 Windows 10/11 (Windows의 경우 (WSL을 통한 접근) 참고)
- Python ≥ 3.11 (런타임 시 표준 라이브러리만 필요)
- PATH에 tmux 및 curl; macOS에서는 zsh (WSL에서는 bash도 무방함)
- Claude Code ≥ 2.1.209
설정 확인을 위해: cc-continuity doctor는 Claude Code 버전을 확인하며, WSL E2E 스크립트(tools/e2e_wsl.sh)는 회전(rotation)/훅 경로를 엔드투엔드(end-to-end)로 테스트합니다.
Windows (WSL을 통한 접근)
cc-continuity는 Windows Subsystem for Linux(WSL) 배포판 내부에서 실행됩니다. 리눅스 측은 변경되지 않았습니다. 동일한 회전 기능, 동일한 워치독(watchdog), 동일한 ntfy 푸시가 적용되며 데몬 호스팅만 다릅니다. macOS가 launchd를 사용하는 반면, 이 배포판은 분리된(detached) tmux 세션(기본값) 또는 시스템d 사용자 유닛(systemd 활성화된 WSL 2의 경우)을 사용하며, WSL VM이 재시작될 때 데몬이 다시 시작되도록 하는 선택적 Windows 로그인 작업이 추가됩니다.
- WSL 2 권장; WSL 1도 작동합니다 (단, systemd 옵션은 제외)
- Ubuntu 24.04 권장; Ubuntu 22.04는 deadsnakes의
python3.11로 작동합니다.
- 네이티브 Windows는 범위를 벗어납니다 — 배포판 자체가 실행 환경입니다.
전체 가이드(요구 사항, 설치, 워치독, 자동 시작, 문제 해결): docs/WINDOWS.md. WSL 설치를 위한 엔드투엔드 테스트는 tools/e2e_wsl.sh에 있습니다.
빠른 시작 (Quick start)
Git에서:
From PyPI:
pip install cc-continuity
cc-continuity install
exec zsh
...
Windows(WSL)에서는 동일한 단계가 디스트로 내부(로그인 셸로 bash 사용)에서 실행됩니다. 전체 WSL 가이드는 docs/WINDOWS.md를 참조하세요.
설치 프로그램은 다음 위치의 모든 파일(식별 가능한 관리 블록이며, cc-continuity uninstall을 통해 모두 되돌릴 수 있음)에 변경 사항을 적용합니다: ~/.claude/settings.json의 hooks + 상태 표시줄, ~/.claude/CLAUDE.md의 관리 블록, ~/.zshrc의 claude() 래퍼(wrapper), 여섯 개의 /continuity-* 스킬, PATH에 있는 cc-continuity 런처, 그리고 ~/.claude-continuity/app/의 앱 복사본입니다. 병합(merge)이 발생하기 전에 settings.json의 타임스탬프가 찍힌 백업 파일이 작성됩니다.
일상 사용 (Daily use)
상태 표시줄을 확인하세요: 문맥 비율(context ratio)이 상승합니다 (기본 임계값 55% 경고 → 62% 로테이트 → 72% 하드 천장). 로테이션은 터치(조작)가 필요 없습니다 (위의 빠른 시작 목록 참조). 충돌, 절전 모드 또는 재부팅 후에는 프로젝트에서 단순히 claude를 실행하고 "continue"라고 말하면 됩니다.
세션 내 명령어: /continuity-status, /continuity-checkpoint, /continuity-rotate, /continuity-off / /continuity-on, /continuity-history. 전체 CLI 참조: docs/USAGE.md.
설정 (Configuration)
전역(Global): ~/.claude-continuity/config.json에서 시작하며, config.example.json의 모든 키와 자리 표시자 값들을 사용합니다. 프로젝트별 재정의(Per-project override): .claude/continuity.json (예: 하나의 프로젝트를 제외하려면 {"enabled": false}).
CC_CONTINUITY=0은 한 번 실행 시 모든 기능을 비활성화합니다.
알림 (Notifications) (ntfy, 옵트인)
cc-continuity는 라이프사이클 이벤트를 ntfy와 호환되는 모든 서버로 푸시할 수 있으므로, 휴대폰에서 장시간 방치된 실행을 모니터링할 수 있습니다:
cc-continuity configure --ntfy https://ntfy.sh/your-topic
cc-continuity configure --ntfy off
cc-continuity doctor는 엔드포인트를 검증하기 위해 테스트 메시지를 전송합니다.
<table>
<thead>
<tr>
<th>이벤트</th>
<th>제목</th>
<th>의미</th>
</tr>
</thead>
<tbody>
<tr>
<td>start</td>
<td>`▶ session started`</td>
<td>세션이 자신을 등록함 (첫 번째 후크 또는 재개 주장)</td>
</tr>
</tbody></table>
개인정보 보호(Privacy): 푸시 알림은 프로젝트 슬러그, 세션 번호, 컨텍스트 비율, 사용자가 제어하는 짧은 이유/요약, 그리고 호스트 이름만 포함하며, 길이는 최대 200자입니다. 파일 내용, 프롬프트, 비밀 정보는 포함되지 않으며, 기록된 텍스트는 전송 과정에서 비밀 정보가 가려집니다(secret-redacted). 메시지는 사용자가 구성하는 엔드포인트로만 전달되며, notify_enabled가 활성화되어 있을 때에만 전달됩니다.
비감독 모드 (Unattended mode) (선택 사항)
⚠️ 경고: launch --unattended를 실행하거나 전체 프로젝트의 경우 config.json: "unattended": true를 설정하면, 에이전트는 claude --dangerously-skip-permissions와 함께 세션을 생성합니다. 이 모드에서는 에이전트가 액션별 승인 없이 파일을 편집하고 명령을 실행합니다. 이는 신뢰하는 머신/프로젝트에서만 사용해야 합니다. needs-human 메커니즘(아래 참조)은 에이전트가 보내는 신호일 뿐, 권한 경계는 아닙니다. 이 메커니즘은 아무것도 강제하거나 차단하지 않습니다. 기본 모드는 변경되지 않으며, 선택적으로 참여하지 않는 한 어떠한 것도 권한을 건너뛰지 않습니다.
claude --unattended
cc-continuity launch --unattended
cc-continuity configure --unattended
롤레이션(rotation)은 동일한 프로세스 내의 /clear이기 때문에, 하나의 플래그(또는 하나의 프로젝트 설정)가 전체 롤레이션 체인을 담당합니다. 즉, 모든 후속 세션이 비감독 상태를 유지합니다.
사용자가 개입해야 할 때 (When it blocks on you)
에이전트는 안전하게 계속 진행할 수 없을 때 사용자에게 신호를 보냅니다 (파괴적/비가역적 작업, 모호한 요구 사항, 동일한 수정이 세 번 실패하는 경우 등):
cc-continuity signal needs-human "<간단한 이유>"
이는 긴급 알림을 푸시하고 상태 표시줄에 ⛔ BLOCKED를 표시합니다 (머신 측의 진실이며, 나중에 연결할 때마다 보임). 패널로 원격 접속하여 세션에서 답장하면, 다음 프롬프트에서 차단이 해제됩니다. 완료 시 에이전트는 다음을 실행합니다:
cc-continuity signal done "<한 줄 요약>"
Watchdog (선택 사항)
장시간 실행을 복구 가능하게 유지하는 데몬(macOS의 launchd; WSL에서의 tmux 세션 또는 systemd 사용자 유닛): 모델 서버용 상태 확인 프로브(2-회 실패 디바운스), 세션별 활성 분류, 경계가 있는 넛지 상태 기계(세션이 자신의 차례가 왜 중단되었는지 통보받음), 종료 지연 방지기(exit-hang killer), 동결된 턴 에스컬레이션, 그리고 선택적 박스 자동 전원 사이클 및 활성 세션으로 전달되는 로그 다이제스트. 기본적으로 비활성화되어 있으며, 상태 확인 URL은 사용자가 제공해야 합니다. 자세한 내용은: docs/WATCHDOG.md.
보안
설치 전에 SECURITY.md를 읽어보십시오. 여기에는 신뢰 모델(trust model)이 명시되어 있습니다: 어떤 코드가 사용자의 권한으로 실행되는지, 설치 프로그램이 무엇을 병합하고 어떻게 제거하는지, 그리고 어떤 데이터가 기기를 떠나는지에 대한 내용입니다.
제한 사항
LIMITATIONS.md를 참조하십시오(솔직한 목록).
개발
테스트는 모든 상태를 CC_CONTINUITY_HOME(임시 디렉토리)을 통해 리디렉션하며, 임시 git 저장소를 사용합니다. 실제 ~/.claude-continuity 또는 ~/.claude에는 절대 접근하지 않습니다. 아키텍처: docs/ARCHITECTURE.md.
라이선스
MIT이며, LICENSE를 참조하십시오.
