​
Управление сессиями

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 предоставляет надежную основу для поддержания состояния разговора и обеспечения бесшовного возобновления задач разработки, все это через простой файловый подход, который не требует внешней инфраструктуры.