​
Manajemen Sesi

Claude Code SDK menyediakan kemampuan manajemen sesi untuk menangani status percakapan, persistensi, dan pemulihan. Panduan ini mencakup bagaimana sesi dibuat, dikelola, disimpan ke file, dan dilanjutkan dalam SDK.

​
Arsitektur Sesi

Claude Code SDK mengimplementasikan sistem manajemen sesi berbasis file yang menangani persistensi percakapan dan pemulihan status.

​
Struktur File Sesi

Sesi disimpan ke sistem file lokal dalam format terstruktur: 
~/.config/claude/
├── sessions/
│   └── sessions.json          # Metadata dan status sesi
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # Transkrip sesi

​
Format Metadata Sesi

File sessions.json menyimpan metadata tentang semua sesi: 
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
  }
}

​
Format Transkrip Sesi

Transkrip sesi disimpan sebagai file JSONL (JSON Lines), dengan setiap baris mewakili pesan atau event: 
{"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"}
Setiap baris dalam file JSONL mewakili:
  • Pesan pengguna: Input dari pengguna
  • Pesan asisten: Respons dari Claude
  • Checkpoint: Status tersimpan dalam percakapan (misalnya, setelah menyelesaikan tugas)
  • Penggunaan tool: Catatan kapan tool dipanggil dan hasilnya

​
Siklus Hidup Sesi

​
Pembuatan dan Inisialisasi

Ketika sesi dimulai, SDK melakukan beberapa langkah inisialisasi:
  1. Generate Session ID: Membuat identifier unik untuk sesi
  2. Buat Direktori Proyek: Menyiapkan lokasi penyimpanan khusus proyek
  3. Inisialisasi File Transkrip: Membuat file JSONL kosong untuk percakapan
  4. Simpan Metadata Awal: Mencatat waktu pembuatan sesi dan konfigurasi

​
Mendapatkan Session ID

Session ID disediakan dalam pesan sistem awal ketika Anda memulai percakapan. Anda dapat menangkapnya untuk digunakan nanti: 
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "Help me build a web application",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // Pesan pertama adalah pesan init sistem dengan session ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session started with ID: ${sessionId}`)
    // Anda dapat menyimpan ID ini untuk pemulihan nanti
  }
  
  // Proses pesan lainnya...
  console.log(message)
}

// Nanti, Anda dapat menggunakan sessionId yang disimpan untuk melanjutkan
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue where we left off",
    options: {
      resume: sessionId
    }
  })
}

​
Persistensi Status Sesi

SDK secara otomatis menyimpan status sesi ke disk:
  • Setelah setiap pertukaran pesan: Transkrip diperbarui
  • Pada pemanggilan tool: Penggunaan tool dan hasil dicatat
  • Pada checkpoint: Status percakapan penting ditandai
  • Pada akhir sesi: Status akhir disimpan

​
Pemulihan Sesi

SDK mendukung pemulihan sesi dari status percakapan sebelumnya, memungkinkan alur kerja pengembangan yang berkelanjutan.

​
Lanjutkan dari File Sesi

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

// Lanjutkan sesi sebelumnya menggunakan ID-nya
const response = query({
  prompt: "Continue implementing the authentication system from where we left off",
  options: {
    resume: "session-xyz", // Session ID dari percakapan sebelumnya
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// Percakapan berlanjut dengan konteks penuh dari sesi sebelumnya
for await (const message of response) {
  console.log(message)
}

​
Penanganan Error dan Pemulihan

​
Menangani Sesi yang Terputus

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

// Periksa apakah sesi terputus
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('Session was interrupted. Ready for resumption...')
    
    // SDK menangani pemuatan transkrip secara internal
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// Lanjutkan sesi yang terputus
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "Let's continue from where we left off",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
Sistem manajemen sesi Claude Code SDK menyediakan fondasi yang kuat untuk mempertahankan status percakapan dan memungkinkan pemulihan tugas pengembangan yang mulus, semuanya melalui pendekatan berbasis file sederhana yang tidak memerlukan infrastruktur eksternal.