​
Gerenciamento de Sessões

O Claude Code SDK fornece capacidades de gerenciamento de sessões para lidar com estado de conversação, persistência e retomada. Este guia aborda como as sessões são criadas, gerenciadas, persistidas em arquivos e retomadas dentro do SDK.

​
Arquitetura de Sessões

O Claude Code SDK implementa um sistema de gerenciamento de sessões baseado em arquivos que lida com persistência de conversação e restauração de estado.

​
Estrutura de Arquivos de Sessão

As sessões são persistidas no sistema de arquivos local em um formato estruturado: 
~/.config/claude/
├── sessions/
│   └── sessions.json          # Metadados e estado da sessão
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # Transcrição da sessão

​
Formato de Metadados da Sessão

O arquivo sessions.json armazena metadados sobre todas as sessões: 
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
  }
}

​
Formato de Transcrição da Sessão

As transcrições de sessão são armazenadas como arquivos JSONL (JSON Lines), com cada linha representando uma mensagem ou evento: 
{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Olá Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"Olá! Como posso ajudar?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"Estado inicial","id":"chk456"}
Cada linha no arquivo JSONL representa:
  • Mensagens do usuário: Entrada do usuário
  • Mensagens do assistente: Respostas do Claude
  • Pontos de verificação: Estados salvos na conversação (por exemplo, após completar uma tarefa)
  • Uso de ferramentas: Registros de quando as ferramentas foram invocadas e seus resultados

​
Ciclo de Vida da Sessão

​
Criação e Inicialização

Quando uma sessão inicia, o SDK executa várias etapas de inicialização:
  1. Gerar ID da Sessão: Cria um identificador único para a sessão
  2. Criar Diretório do Projeto: Configura o local de armazenamento específico do projeto
  3. Inicializar Arquivo de Transcrição: Cria um arquivo JSONL vazio para a conversação
  4. Armazenar Metadados Iniciais: Registra o tempo de criação da sessão e configuração

​
Obtendo o ID da Sessão

O ID da sessão é fornecido na mensagem inicial do sistema quando você inicia uma conversação. Você pode capturá-lo para uso posterior: 
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "Me ajude a construir uma aplicação web",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // A primeira mensagem é uma mensagem de inicialização do sistema com o ID da sessão
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sessão iniciada com ID: ${sessionId}`)
    // Você pode salvar este ID para retomada posterior
  }
  
  // Processar outras mensagens...
  console.log(message)
}

// Posteriormente, você pode usar o sessionId salvo para retomar
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continue de onde paramos",
    options: {
      resume: sessionId
    }
  })
}

​
Persistência do Estado da Sessão

O SDK persiste automaticamente o estado da sessão no disco:
  • Após cada troca de mensagens: A transcrição é atualizada
  • Em invocações de ferramentas: O uso de ferramentas e resultados são registrados
  • Em pontos de verificação: Estados importantes da conversação são marcados
  • No final da sessão: O estado final é salvo

​
Retomada de Sessão

O SDK suporta retomar sessões de estados de conversação anteriores, permitindo fluxos de trabalho de desenvolvimento contínuos.

​
Retomar de Arquivos de Sessão

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

// Retomar uma sessão anterior usando seu ID
const response = query({
  prompt: "Continue implementando o sistema de autenticação de onde paramos",
  options: {
    resume: "session-xyz", // ID da sessão da conversação anterior
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// A conversação continua com contexto completo da sessão anterior
for await (const message of response) {
  console.log(message)
}

​
Tratamento de Erros e Recuperação

​
Lidando com Sessões Interrompidas

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

// Verificar se uma sessão foi interrompida
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('Sessão foi interrompida. Pronta para retomada...')
    
    // O SDK lida com o carregamento da transcrição internamente
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// Retomar uma sessão interrompida
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "Vamos continuar de onde paramos",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
O sistema de gerenciamento de sessões do Claude Code SDK fornece uma base robusta para manter o estado da conversação e permitir a retomada perfeita de tarefas de desenvolvimento, tudo através de uma abordagem simples baseada em arquivos que não requer infraestrutura externa.