​
Gestión de Sesiones

El Claude Code SDK proporciona capacidades de gestión de sesiones para manejar el estado de conversación, persistencia y reanudación. Esta guía cubre cómo se crean, gestionan, persisten en archivos y reanudan las sesiones dentro del SDK.

​
Arquitectura de Sesiones

El Claude Code SDK implementa un sistema de gestión de sesiones basado en archivos que maneja la persistencia de conversaciones y la restauración de estado.

​
Estructura de Archivos de Sesión

Las sesiones se persisten en el sistema de archivos local en un formato estructurado: 
~/.config/claude/
├── sessions/
│   └── sessions.json          # Metadatos y estado de sesión
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # Transcripción de sesión

​
Formato de Metadatos de Sesión

El archivo sessions.json almacena metadatos sobre todas las sesiones: 
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 Transcripción de Sesión

Las transcripciones de sesión se almacenan como archivos JSONL (JSON Lines), con cada línea representando un mensaje o evento: 
{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Hola Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"¡Hola! ¿Cómo puedo ayudar?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"Estado inicial","id":"chk456"}
Cada línea en el archivo JSONL representa:
  • Mensajes de usuario: Entrada del usuario
  • Mensajes del asistente: Respuestas de Claude
  • Puntos de control: Estados guardados en la conversación (ej., después de completar una tarea)
  • Uso de herramientas: Registros de cuándo se invocaron herramientas y sus resultados

​
Ciclo de Vida de la Sesión

​
Creación e Inicialización

Cuando una sesión comienza, el SDK realiza varios pasos de inicialización:
  1. Generar ID de Sesión: Crea un identificador único para la sesión
  2. Crear Directorio de Proyecto: Configura la ubicación de almacenamiento específica del proyecto
  3. Inicializar Archivo de Transcripción: Crea un archivo JSONL vacío para la conversación
  4. Almacenar Metadatos Iniciales: Registra el tiempo de creación de la sesión y configuración

​
Obtener el ID de Sesión

El ID de sesión se proporciona en el mensaje inicial del sistema cuando inicias una conversación. Puedes capturarlo para uso posterior: 
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "Ayúdame a construir una aplicación web",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // El primer mensaje es un mensaje init del sistema con el ID de sesión
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sesión iniciada con ID: ${sessionId}`)
    // Puedes guardar este ID para reanudación posterior
  }
  
  // Procesar otros mensajes...
  console.log(message)
}

// Más tarde, puedes usar el sessionId guardado para reanudar
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continúa donde lo dejamos",
    options: {
      resume: sessionId
    }
  })
}

​
Persistencia de Estado de Sesión

El SDK persiste automáticamente el estado de la sesión en disco:
  • Después de cada intercambio de mensajes: La transcripción se actualiza
  • En invocaciones de herramientas: Se registran el uso de herramientas y resultados
  • En puntos de control: Se marcan estados importantes de la conversación
  • Al final de la sesión: Se guarda el estado final

​
Reanudación de Sesión

El SDK soporta reanudar sesiones desde estados de conversación previos, habilitando flujos de trabajo de desarrollo continuos.

​
Reanudar desde Archivos de Sesión

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

// Reanudar una sesión previa usando su ID
const response = query({
  prompt: "Continúa implementando el sistema de autenticación desde donde lo dejamos",
  options: {
    resume: "session-xyz", // ID de sesión de conversación previa
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// La conversación continúa con contexto completo de la sesión previa
for await (const message of response) {
  console.log(message)
}

​
Manejo de Errores y Recuperación

​
Manejo de Sesiones Interrumpidas

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

// Verificar si una sesión fue interrumpida
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('La sesión fue interrumpida. Lista para reanudación...')
    
    // El SDK maneja la carga de la transcripción internamente
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// Reanudar una sesión interrumpida
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "Continuemos desde donde lo dejamos",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
El sistema de gestión de sesiones del Claude Code SDK proporciona una base robusta para mantener el estado de conversación y habilitar la reanudación sin problemas de tareas de desarrollo, todo a través de un enfoque simple basado en archivos que no requiere infraestructura externa.