클로드 코드 세션이 끊겨도 하던 일을 잇는 법 — 체크포인트 한 파일

클로드 코드로 작업하다 보면 하루에도 몇 번씩 같은 자리로 돌아옵니다. 컨텍스트가 한 번 압축되거나, 창을 닫았거나, 한도에 걸렸을 때입니다. 그때마다 "우리 어디까지 했었지"를 처음부터 다시 설명하게 됩니다.

이상한 건 대화 원문은 멀쩡히 남아 있다는 점입니다. 클로드 코드는 모든 세션을 ~/.claude/projects/ 아래에 기록으로 남깁니다. 남지 않는 건 대화가 아니라 지금 어디인가입니다. 그 한 줄이 없어서 매번 전체를 다시 훑습니다.

그래서 상태를 적어두는 층을 하나 만들었습니다. 이 글은 그게 왜 이렇게 생겼는지, 어떻게 도는지, 그리고 코드 전문입니다.

배경 — 시켰는데 안 만든 부분이 있습니다

시작은 사장님이 가져온 「세션 매니저」 구상이었습니다. 세션 상태를 관리하고, 한도에 걸리면 다음 계정으로 자동 전환한다는 내용이었어요.

뒷부분은 만들지 않았습니다. 계정을 돌려가며 사용량 제한을 넘기는 자동화는 이용정책 위반이라서요. 한도가 자주 걸린다면 답은 요금제이거나, 한도가 없는 로컬 모델입니다. 우회 도구가 아닙니다.

대신 그 구상에서 쓸 수 있는 부분 하나를 남겼습니다. 상태 층입니다. 이게 이 글의 전부고, 실제로 매일 씁니다.

작동 원리 ① — 사람이 안 적어도 남는다

처음 만든 버전은 사람이 save 를 눌러야 하는 구조였습니다. 사장님이 바로 되물었어요. "이게 최선은 아닌 것 같은데?" 맞는 지적이었습니다. 저장을 기억해야 도는 장치는 정작 급할 때 안 돌아갑니다. 끊기는 순간은 예고가 없으니까요.

그래서 방향을 뒤집었습니다. 사람에게 묻지 않고 세션 기록에서 거꾸로 복구합니다. 기록 파일에서 제목, 마지막 요청, 마지막 보고, 손댄 파일, 커밋을 뽑아냅니다. 파일이 크기 때문에 통째로 읽지 않고 앞부분과 뒷부분만 잘라 읽습니다. 1초 안팎입니다.

돌리는 건 훅입니다. 세 자리에 겁니다.

• Stop — 매 턴이 끝날 때마다
• PreCompact — 컨텍스트가 압축되기 직전, 지워지기 전 마지막 스냅샷
• SessionStart — 새 세션이 열릴 때 요약을 컨텍스트에 넣는다

커밋할 때마다 git 사실을 얹는 post-commit 훅도 하나 답니다. 그래서 사람이 손으로 적는 건 기록이 담지 못하는 것뿐입니다. 왜 하는지, 다음이 뭔지, 뭐에 막혔는지. 그마저 안 적으면 기록에서 유추한 값이 들어갑니다.

작동 원리 ② — 파일은 하나, 보는 자리는 셋

상태가 파일 하나(docs/checkpoint.json)에 있으니, 그 파일을 보는 자리를 늘릴 수 있습니다. 지금 셋입니다.

오픈코드 쪽은 세션을 SQLite 로 보관합니다. 그 DB 를 읽기 전용으로 열어 클로드 기록과 한 목록에 섞어 보여줍니다. 어느 쪽에서 일해도 다음 세션의 첫 화면에 보입니다. 옮기는 작업이 따로 없습니다.

작동 원리 ③ — 챗지피티는 읽기만 합니다

세 번째 창구는 챗지피티 웹입니다. 커스텀 MCP 커넥터로 붙였습니다. 여기서 한 가지를 분명히 하고 갑니다. 남의 MCP 서버를 쓰지 않았습니다.

화제가 됐던 공개 서버 하나를 격리된 환경에서 검증해 봤는데, 셸 명령이 허용 폴더 밖까지 걸렸습니다. 챗지피티에 셸을 준다는 건 그 구멍을 내 작업 폴더에 여는 것과 같습니다. 그래서 직접 만들었고, 도구 다섯 개가 전부 읽기입니다.

• checkpoint — 지금 어디까지 했나
• search / fetch — 기억을 섹션 단위로 검색하고 본문 가져오기
• memory_log — 최근 세션 요약
• memory_topic — 주제별 지식 파일

여는 범위도 목록으로 못 박았습니다. 체크포인트, 세션 요약, 주제 지식, 문서까지입니다. 코드와 .env, 토큰, 쿠키는 목록에 없어서 못 읽습니다. 실제로 시켜봤습니다.

그대로 가져가세요

훅 설정은 이게 전부입니다. .claude/settings.json 에 넣습니다.

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "node tools/checkpoint.mjs recover --quiet", "timeout": 20 } ] }
    ],
    "PreCompact": [
      { "hooks": [ { "type": "command", "command": "node tools/checkpoint.mjs recover --quiet", "timeout": 20 } ] }
    ],
    "SessionStart": [
      { "hooks": [ { "type": "command", "command": "node tools/checkpoint.mjs show --brief", "timeout": 20 } ] }
    ]
  }
}

쓰는 명령은 넷입니다.

# 세션 시작 — 지금 어디인지 + 최근 세션들이 뭘 했나
node tools/checkpoint.mjs show
node tools/checkpoint.mjs show --brief --hours 240

# 기록에서 복구 (훅이 알아서 부릅니다)
node tools/checkpoint.mjs recover --quiet

# 사람이 목표를 명시 — 기록이 못 담는 것만
node tools/checkpoint.mjs save --goal "릴스 다듬기 패널" --next "슬라이더 배선;프리뷰 재촬영" --blocked "8795 죽으면 503"

# post-commit 훅 설치 (처음 한 번)
node tools/checkpoint.mjs hook

# 목표가 끝나면 비운다
node tools/checkpoint.mjs done

이게 못 하는 것

기대치를 정확히 적어둡니다.

• 끊긴 순간의 대화 자체는 못 살립니다. 남는 건 목표, 다음 할 일, git 사실입니다. 대화를 그대로 이으려면 같은 계정·같은 기계에서 claude --resume 을 씁니다.
• 다른 기계로는 git 에 든 것만 갑니다. .env·토큰·쿠키는 안 따라갑니다. 그게 맞습니다.
• 계정 전환은 없습니다. 앞에서 적은 이유 그대로입니다.
• 복구는 말을 옮길 뿐입니다. 마지막 요청이 "다시 시도" 같은 한마디면 목표가 안 보입니다. 그럴 때만 사람이 한 줄 적습니다.

기억을 파일로 관리하는 더 넓은 얘기는 클로드 메모리 시스템 4단계에 정리해 뒀습니다. 이 글의 체크포인트는 그중 "지금 위치"만 떼어낸 조각입니다.

카드로 한 번에 보기