Gestione delle Sessioni

Il Claude Code SDK fornisce capacità di gestione delle sessioni per gestire lo stato della conversazione, la persistenza e la ripresa. Questa guida copre come le sessioni vengono create, gestite, persistite su file e riprese all’interno del SDK.

Architettura delle Sessioni

Il Claude Code SDK implementa un sistema di gestione delle sessioni basato su file che gestisce la persistenza della conversazione e il ripristino dello stato.

Struttura dei File di Sessione

Le sessioni vengono persistite nel filesystem locale in un formato strutturato:
~/.config/claude/
├── sessions/
│   └── sessions.json          # Metadati e stato della sessione
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # Trascrizione della sessione

Formato dei Metadati della Sessione

Il file sessions.json memorizza i metadati di tutte le sessioni:
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 della Trascrizione della Sessione

Le trascrizioni delle sessioni vengono memorizzate come file JSONL (JSON Lines), con ogni riga che rappresenta un messaggio o evento:
{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Ciao Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"Ciao! Come posso aiutarti?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"Stato iniziale","id":"chk456"}
Ogni riga nel file JSONL rappresenta:
  • Messaggi utente: Input dall’utente
  • Messaggi assistente: Risposte da Claude
  • Checkpoint: Stati salvati nella conversazione (ad esempio, dopo aver completato un’attività)
  • Uso strumenti: Registrazioni di quando gli strumenti sono stati invocati e i loro risultati

Ciclo di Vita della Sessione

Creazione e Inizializzazione

Quando una sessione inizia, il SDK esegue diversi passaggi di inizializzazione:
  1. Genera ID Sessione: Crea un identificatore unico per la sessione
  2. Crea Directory Progetto: Imposta la posizione di archiviazione specifica del progetto
  3. Inizializza File Trascrizione: Crea un file JSONL vuoto per la conversazione
  4. Memorizza Metadati Iniziali: Registra il tempo di creazione della sessione e la configurazione

Ottenere l’ID Sessione

L’ID sessione viene fornito nel messaggio di sistema iniziale quando si avvia una conversazione. Puoi catturarlo per un uso successivo:
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "Aiutami a costruire un'applicazione web",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // Il primo messaggio è un messaggio init di sistema con l'ID sessione
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Sessione avviata con ID: ${sessionId}`)
    // Puoi salvare questo ID per la ripresa successiva
  }
  
  // Elabora altri messaggi...
  console.log(message)
}

// Successivamente, puoi usare il sessionId salvato per riprendere
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continua da dove abbiamo lasciato",
    options: {
      resume: sessionId
    }
  })
}

Persistenza dello Stato della Sessione

Il SDK persiste automaticamente lo stato della sessione su disco:
  • Dopo ogni scambio di messaggi: La trascrizione viene aggiornata
  • Sulle invocazioni degli strumenti: L’uso degli strumenti e i risultati vengono registrati
  • Ai checkpoint: Gli stati importanti della conversazione vengono contrassegnati
  • Alla fine della sessione: Lo stato finale viene salvato

Ripresa della Sessione

Il SDK supporta la ripresa delle sessioni da stati di conversazione precedenti, abilitando flussi di lavoro di sviluppo continui.

Riprendi dai File di Sessione

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

// Riprendi una sessione precedente usando il suo ID
const response = query({
  prompt: "Continua a implementare il sistema di autenticazione da dove abbiamo lasciato",
  options: {
    resume: "session-xyz", // ID Sessione dalla conversazione precedente
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// La conversazione continua con il contesto completo dalla sessione precedente
for await (const message of response) {
  console.log(message)
}

Gestione degli Errori e Recupero

Gestione delle Sessioni Interrotte

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

// Controlla se una sessione è stata interrotta
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 sessione è stata interrotta. Pronta per la ripresa...')
    
    // Il SDK gestisce il caricamento della trascrizione internamente
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// Riprendi una sessione interrotta
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "Continuiamo da dove abbiamo lasciato",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
Il sistema di gestione delle sessioni del Claude Code SDK fornisce una base robusta per mantenere lo stato della conversazione e abilitare la ripresa senza soluzione di continuità delle attività di sviluppo, tutto attraverso un approccio semplice basato su file che non richiede infrastruttura esterna.