ctx-handoff: Claude Code 긴 세션을 더 편하게

ctx-handoff는 CabLate(cablate)가 만든 커뮤니티 모드로, Claude Code 긴 세션, 즉 몇 시간씩 이어지는 대화를 위한 것입니다. 긴 대화에서 반복되는 잡무를 한데 묶었습니다. 자리를 비운 동안 아주 작은 요청을 보내 프롬프트 캐시가 만료되지 않게 하고, 반복한 지시를 프로젝트별 노트로 만들어 새 대화에 불러오며, Claude가 실패한 도구를 다시 시도하거나 검증 없이 "완료"라고 말하면 한마디 건넵니다.

더 큰 기능 두 가지는 자동이 아닙니다. 선택 사항인 인계는 컨텍스트가 임계값에 이르면 작업 요약을 쓰고 대화를 지운 뒤 새 대화에서 이어 가며, 기본값은 꺼짐입니다. 가드는 반복한 규칙으로 모드가 초안을 만드는 도구 호출 점검이며, 승인한 뒤에만 적용됩니다. 프롬프트 위의 패널(/handoff panel)에는 가드, 메모리, 규칙, 최근 노트 업데이트, 모든 설정이 표시됩니다.

작성자의 README는 Claude 구독과 큰 컨텍스트의 긴 세션을 대상으로 합니다. API 키, Bedrock, Vertex에서는 캐시가 5분만 유지되므로 작성자는 /handoff refresh off를 권합니다.

녹화에서는 작은 데모 프로젝트에서 이 모드를 불러온 Claude Code를 시작합니다. 푸터에 곧바로 ctx-handoff: 30 more messages until notes update가 나타납니다. 다음 백그라운드 노트 업데이트까지의 카운트다운입니다. 이어서 /handoff guard를 실행하면 Guards: none과 가드 초안이 만들어지는 조건이 출력되고, /handoff refresh는 Currently on. Usage: /handoff refresh on|off를 출력합니다. 녹화 중에는 모델 요청이 없으며 패널도 열지 않습니다. 패널에는 노트 파일의 전체 경로가 표시되기 때문입니다.

설치 블록의 어느 방법이든 사용하세요. 모두 작성자 본인의 마켓플레이스에서 바로 설치합니다. 새 세션을 시작하고 /handoff를 실행하세요. 세션이 시작되면 푸터에 카운트다운이 나타납니다.

모든 기능은 모듈 하나, hooks/register.ts에서 등록됩니다. 턴이 끝날 때마다 유휴 타이머가 다시 시작됩니다. 타이머가 울리고 컨텍스트가 min_tokens보다 크면, 캐시된 대화를 읽기 위한 최소한의 fork 요청을 보낸 뒤 다음 갱신을 예약합니다. 다음은 스케줄 함수로, hooks/register.ts에서 가져왔습니다.

async function schedule($: EngineInterface, delay = cfg.idleMs) {
  rt.idle?.cancel()
  if (await awayPaused($)) { rt.idle = undefined; await update($, idleState, () => null); return }
  rt.idle = $.clock.after(delay, () => void onIdle($))
  const due = (await $.clock.now()) + delay
  await update($, idleState, () => ({ due, refreshes: rt.refreshes }))
}

기본 유휴 시간은 50분이고 갱신은 최대 3번이며, 그 뒤에는 대화를 지우지 않고 자리 비움 인계를 저장합니다. 사용자 메시지 30개마다, 또는 인계 전에, 기록 없이 보내는 별도 요청이 대화의 새 부분만 노트 모델(claude-sonnet-5-5, 낮은 추론 강도)에 보냅니다. 모델이 돌려준 JSON 동작은 코드로 검증하며, 사용자 인용문은 실제 메시지에서 찾을 수 있어야 하고, 비밀 정보처럼 보이는 줄은 쓰기 전에 버립니다. 노트는 prompt.context로 새 대화에 주입됩니다.

이 모드는 userConfig를 선언하지 않습니다. 설정은 패널의 설정 탭(/handoff panel을 열고 5번 키)에 있으며, settings.json의 pluginConfigs["ctx-handoff@<marketplace>"].options도 읽습니다. 둘 다 있으면 패널 값이 우선합니다. 설정에는 auto_handoff(기본 꺼짐), threshold(600000토큰), idle_minutes(50), max_refresh(3), min_tokens(30000), distill_every(30), notes_model, retry_nudge, done_check, reply_language, language가 있습니다. 나머지는 슬래시 명령으로 다룹니다. /handoff now, dry, distill on|off, refresh on|off, away pause|resume, guard, resume, continue, resend입니다.

매니페스트, hooks/hooks.json, hooks/register.ts 전체, 그리고 설정, 노트, 인계, 가드, 루프, 언어, 승격, 정리 프롬프트 모듈을 읽었습니다. 나머지 파일은 주로 i18n 문자열, 패널 화면, 작은 기록 도우미이며, 한 줄씩 읽는 대신 검색으로 부작용이 없는지 확인했습니다. 저장소에는 package.json, 설치 스크립트, 바이너리, 압축된 코드가 없습니다. tools/에는 작성자용 스크립트가 있으며 플러그인은 불러오지 않고 저희도 실행하지 않았습니다. 숨겨진 유니코드 문자는 없습니다.

알아 두어야 할 점:

• 모델 요청은 있지만 다른 네트워크 접근은 없습니다. fetch, 프로세스 호출, 네트워크 코드가 없습니다. 모드는 $.model.fork와 $.model.complete를 호출하며 Claude 사용량을 씁니다. 대화 내용은 노트와 인계 요약을 위해, 대화 자체와 같은 방식으로 전송됩니다.
• 자체 저장소 밖에 씁니다. $.fs.write가 <claude 설정 디렉터리>/projects/<작업 공간>/memory/ctx-handoff.md를 만들고 갱신하며, 패널에서 노트를 삭제하기 전에 .ctx-handoff-backup/에 백업을 씁니다. 백그라운드 노트 업데이트는 기본으로 켜져 있지만, 홈 폴더에서 시작한 세션에서는 건너뜁니다. settings.json, 셸 파일, LaunchAgents는 건드리지 않으며 HOME, USERPROFILE, CLAUDE_CONFIG_DIR을 읽습니다.
• 모델에 텍스트를 주입합니다. prompt.context는 노트, 선택적 진행 메모, 가드 질문을 [ctx-handoff] 태그와 함께 새 대화에 추가합니다. 도구 결과에 안내 문구가 붙을 수도 있습니다. git 저장소에서 규칙이 3번 반복되면 주입되는 텍스트가 Claude에게 묻지 않고 저장소(CLAUDE.md, .claude/skills, 훅)에 쓰라고 지시합니다. 다만 커밋은 하지 않게 합니다. 노트는 모델이 쓴 대화 요약이므로 가끔 파일을 확인하세요.
• 차단하는 훅. tool.call은 승인한 가드에 대해서만 호출을 거부할 수 있습니다. classic.Stop은 파일을 수정했는데 검사를 돌리지 않았다면 턴마다 한 번 "완료" 답변을 막을 수 있습니다(done_check, 기본 켜짐). prompt.submit은 인계가 진행되는 동안 메시지를 보관합니다. 자동 인계를 켜면 모드가 직접 /clear를 실행하고 요약을 제출합니다.
• 데몬도 텔레메트리도 없습니다. 타이머는 Claude Code 프로세스 안에만 있고, 사용 통계는 플러그인 저장소에 남습니다.
• 관리되는 환경. claude plugin validate에 따르면 조직이 Claude Code를 관리하는 환경에서는 사용자가 설치한 플러그인의 prompt.context와 classic.Stop 훅이 실행되지 않습니다.
• 라이선스. MIT이며 LICENSE 파일이 있습니다.

claude plugin validate는 오류를 보고하지 않았습니다. 경고는 저장소 루트의 CLAUDE.md가 플러그인 컨텍스트로 불러와지지 않는다는 한 가지뿐입니다. 작성자의 15개 파일, 290개 테스트는 Claude Code 2.1.303에서 모두 통과했습니다.

macOS의 Claude Code 2.1.303에서 확인했습니다(validate, 테스트, 녹화). 작성자의 README는 2.1.287 이상을 요구합니다. /handoff가 반응하지 않으면 다음을 확인하세요.

• claude --version이 2.1.287 이상이고, 설치 후 새 세션을 시작했습니다.
• 이미 다른 /handoff 명령이 있다면 모드는 대신 /ctx-handoff를 등록합니다.
• 노트 업데이트가 꺼져 있거나 홈 폴더에서 Claude Code를 시작했다면 푸터 카운트다운이 나타나지 않습니다.
• 캐시 갱신은 캐시가 한 시간 유지되는 환경에서만 도움이 되므로, API 키에서는 /handoff refresh off로 끄세요.
• /handoff를 실행하면 최근 실패와 노트 파일 경로를 포함한 현재 상태를 볼 수 있습니다.