​
세션 관리

Claude Code SDK는 대화 상태, 지속성, 재개를 처리하기 위한 세션 관리 기능을 제공합니다. 이 가이드는 SDK 내에서 세션이 생성, 관리, 파일에 저장, 재개되는 방법을 다룹니다.

​
세션 아키텍처

Claude Code SDK는 대화 지속성과 상태 복원을 처리하는 파일 기반 세션 관리 시스템을 구현합니다.

​
세션 파일 구조

세션은 구조화된 형식으로 로컬 파일시스템에 저장됩니다: 
~/.config/claude/
├── sessions/
│   └── sessions.json          # 세션 메타데이터 및 상태
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # 세션 기록

​
세션 메타데이터 형식

sessions.json 파일은 모든 세션에 대한 메타데이터를 저장합니다: 
interface SessionMetadata {
  id: string
  name: string
  status: 'active' | 'completed' | 'interrupted'
  createdAt: Date
  updatedAt: Date
  completedAt?: Date
  projectPath: string
  transcriptPath: string
  metadata: {
    model?: string
    tools?: string[]
    lastMessageId?: string
  }
}

​
세션 기록 형식

세션 기록은 JSONL(JSON Lines) 파일로 저장되며, 각 줄은 메시지나 이벤트를 나타냅니다: 
{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Hello Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"Hello! How can I help?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"Initial state","id":"chk456"}
JSONL 파일의 각 줄은 다음을 나타냅니다:
  • 사용자 메시지: 사용자의 입력
  • 어시스턴트 메시지: Claude의 응답
  • 체크포인트: 대화에서 저장된 상태 (예: 작업 완료 후)
  • 도구 사용: 도구가 호출되고 그 결과가 기록된 내용

​
세션 생명주기

​
생성 및 초기화

세션이 시작될 때, SDK는 여러 초기화 단계를 수행합니다:
  1. 세션 ID 생성: 세션에 대한 고유 식별자 생성
  2. 프로젝트 디렉토리 생성: 프로젝트별 저장 위치 설정
  3. 기록 파일 초기화: 대화를 위한 빈 JSONL 파일 생성
  4. 초기 메타데이터 저장: 세션 생성 시간 및 구성 기록

​
세션 ID 가져오기

세션 ID는 대화를 시작할 때 초기 시스템 메시지에서 제공됩니다. 나중에 사용하기 위해 캡처할 수 있습니다: 
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "웹 애플리케이션 구축을 도와주세요",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // 첫 번째 메시지는 세션 ID가 포함된 시스템 초기화 메시지입니다
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`세션이 ID로 시작되었습니다: ${sessionId}`)
    // 나중에 재개하기 위해 이 ID를 저장할 수 있습니다
  }
  
  // 다른 메시지 처리...
  console.log(message)
}

// 나중에 저장된 sessionId를 사용하여 재개할 수 있습니다
if (sessionId) {
  const resumedResponse = query({
    prompt: "중단된 지점부터 계속하세요",
    options: {
      resume: sessionId
    }
  })
}

​
세션 상태 지속성

SDK는 세션 상태를 디스크에 자동으로 저장합니다:
  • 각 메시지 교환 후: 기록이 업데이트됩니다
  • 도구 호출 시: 도구 사용 및 결과가 기록됩니다
  • 체크포인트에서: 중요한 대화 상태가 표시됩니다
  • 세션 종료 시: 최종 상태가 저장됩니다

​
세션 재개

SDK는 이전 대화 상태에서 세션을 재개하는 것을 지원하여 지속적인 개발 워크플로우를 가능하게 합니다.

​
세션 파일에서 재개

import { query } from "@anthropic-ai/claude-code"

// 세션 ID를 사용하여 이전 세션 재개
const response = query({
  prompt: "중단된 지점부터 인증 시스템 구현을 계속하세요",
  options: {
    resume: "session-xyz", // 이전 대화의 세션 ID
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// 대화는 이전 세션의 전체 컨텍스트와 함께 계속됩니다
for await (const message of response) {
  console.log(message)
}

​
오류 처리 및 복구

​
중단된 세션 처리

import { query } from '@anthropic-ai/claude-code'
import { readFile } from 'fs/promises'
import { homedir } from 'os'
import { join } from 'path'

// 세션이 중단되었는지 확인
const checkSessionStatus = async (sessionId: string) => {
  const metadataPath = join(homedir(), '.config/claude/sessions/sessions.json')
  const metadata = JSON.parse(await readFile(metadataPath, 'utf-8'))
  
  const session = metadata.find(s => s.id === sessionId)
  
  if (session?.status === 'interrupted') {
    console.log('세션이 중단되었습니다. 재개 준비 완료...')
    
    // SDK가 내부적으로 기록 로드를 처리합니다
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// 중단된 세션 재개
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "중단된 지점부터 계속해봅시다",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
Claude Code SDK의 세션 관리 시스템은 대화 상태를 유지하고 개발 작업의 원활한 재개를 가능하게 하는 견고한 기반을 제공하며, 모든 것이 외부 인프라가 필요 없는 간단한 파일 기반 접근 방식을 통해 이루어집니다.