​
セッション管理

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のセッション管理システムは、会話状態を維持し、開発タスクのシームレスな再開を可能にする堅牢な基盤を提供します。これらはすべて、外部インフラストラクチャを必要としないシンプルなファイルベースのアプローチを通じて実現されます。