세션 관리

Claude Code의 세션 관리 시스템은 대화 히스토리를 추가 전용(append-only) JSONL 파일로 지속하고, parentUuid 기반 연결 리스트로 메시지 체인을 관리하며, 상태 머신으로 세션 수명 주기를 추적합니다. 이 시스템은 중단된 세션의 복구, 효율적인 세션 목록 표시, 클라우드 동기화까지 지원합니다.

세션 파일은 ~/.claude/projects/ 디렉토리 아래에 프로젝트 경로를 반영한 구조로 저장됩니다:

# 디스크 레이아웃 예시
~/.claude/projects/
  └── home-user-myproject/          # 프로젝트 경로 인코딩
      ├── sessions/
      │   ├── abc123.jsonl          # 세션 트랜스크립트 (추가 전용)
      │   └── def456.jsonl
      ├── memory.md                 # 세션 메모리
      └── config.json               # 프로젝트 설정

Project 싱글톤과 쓰기 큐

각 프로젝트는 싱글톤 인스턴스로 관리됩니다. 세션 파일에 대한 쓰기는 100ms 배치 큐를 통해 수행되어 디스크 I/O를 최소화합니다. 짧은 시간 내에 발생하는 여러 메시지 추가가 단일 쓰기 작업으로 통합됩니다.

// projectSingleton.ts — 100ms 배치 쓰기
class WriteQueue {
  private pending: Entry[] = []
  private timer: NodeJS.Timeout | null = null

  enqueue(entry: Entry): void {
    this.pending.push(entry)
    if (!this.timer) {
      this.timer = setTimeout(() => this.flush(), 100)
    }
  }
}

세션 JSONL 파일에는 16종의 엔트리 타입이 기록됩니다. 각 엔트리는 type, uuid, parentUuid, timestamp 필드를 공통으로 가집니다:

• 메시지 타입: user, assistant, system — 대화 메시지
• 도구 타입: tool_use, tool_result — 도구 호출 및 결과
• 메타데이터 타입: session_start, session_end, compaction — 세션 수명 주기
• 상태 타입: interrupted_turn, resumed — 중단 및 복구
• 기타: cost_update, model_change, memory_update, context_window, isMeta — 부가 정보

JSONL 파일의 엔트리는 parentUuid 필드를 통해 연결 리스트를 형성합니다. 이 구조는 대화 브랜칭, 압축 후 재구성, 부분 로드를 가능하게 합니다.

체인 워킹

체인 구축은 리프(LEAF) 메시지에서 시작하여 parentUuid를 따라 역방향으로 워킹한 후, 최종적으로 reverse()를 호출하여 시간순으로 정렬합니다:

// sessionStore.ts — 역방향 체인 워킹
function buildChain(leafUuid: string, entries: Map): Entry[] {
  const chain: Entry[] = []
  let current = entries.get(leafUuid)

  while (current) {
    chain.push(current)
    current = entries.get(current.parentUuid)
  }

  return chain.reverse() // 시간순 정렬
}

사이클 감지

체인 워킹 중 방문한 UUID를 Set으로 추적하여 순환 참조를 감지합니다. 사이클이 감지되면 체인 워킹을 즉시 중단하고 현재까지 수집된 체인을 반환합니다.

세션은 세 가지 상태를 가지는 상태 머신으로 관리됩니다:

• idle: 사용자 입력 대기 상태. 새 프롬프트를 받을 준비가 됨
• running: 모델이 응답을 생성 중이거나 도구를 실행 중
• requires_action: 권한 프롬프트 등 사용자 액션이 필요한 상태

// sessionState.ts — 상태 전이
idle → running          // 사용자 메시지 전송
running → idle          // 모델 응답 완료
running → requires_action  // 권한 프롬프트 필요
requires_action → running  // 사용자가 허용/거부
requires_action → idle     // 사용자가 중단

인터럽트 감지

세션 재개(resume) 시 마지막 메시지가 assistant 타입이고 stop_reason이 없으면, 이전 세션이 비정상 종료(Ctrl+C, 크래시 등)된 것으로 판단합니다. 이 경우 "Continue from where you left off." isMeta 메시지가 자동으로 추가됩니다.

loadConversationForResume — 4개 소스

세션 복구 시 대화 내용을 4개 소스에서 로드합니다:

1. 로컬 JSONL 파일 — 기본 소스
2. 클라우드 저장소 — 로컬 파일이 없을 때 폴백
3. 메모리 캐시 — 최근 세션의 인메모리 캐시
4. 압축된 요약 — 전체 로드가 불가능할 때 압축 요약 사용

클라우드 지속성 (이중 원격 경로)

세션 데이터는 두 개의 원격 경로로 동기화됩니다. 이중 경로는 마이그레이션 기간 동안 이전 경로와 새 경로 모두에서 읽기를 보장합니다.

꼬리 윈도우 메타데이터 (64KB)

세션 목록을 표시할 때 전체 JSONL 파일을 읽지 않고, EOF에서 64KB 꼬리 윈도우만 읽습니다. 메타데이터(session_start, 마지막 메시지 요약 등)는 압축이나 업데이트 시 EOF에 재추가되어 항상 꼬리 윈도우 내에 존재하도록 보장합니다.

// sessionStore.ts — 64KB 꼬리 읽기
function readSessionMetadata(path: string): Metadata {
  const stat = fs.statSync(path)
  const tailOffset = Math.max(0, stat.size - 65536) // 64KB
  const tail = fs.readSync(fd, buffer, tailOffset, 65536)
  return parseMetadataFromTail(tail)
}