Gestion des Sessions

Comprendre comment le SDK Claude Code gère les sessions, les fichiers de session et la reprise de session

Gestion des Sessions

Le SDK Claude Code fournit des capacités de gestion de session pour gérer l’état des conversations, la persistance et la reprise. Ce guide couvre comment les sessions sont créées, gérées, persistées dans des fichiers et reprises au sein du SDK.

Architecture des Sessions

Le SDK Claude Code implémente un système de gestion de session basé sur des fichiers qui gère la persistance des conversations et la restauration d’état.

Structure des Fichiers de Session

Les sessions sont persistées dans le système de fichiers local dans un format structuré :

~/.config/claude/
├── sessions/
│   └── sessions.json          # Métadonnées et état de session
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # Transcription de session

Format des Métadonnées de Session

Le fichier sessions.json stocke les métadonnées de toutes les sessions :

TypeScript

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
  }
}

Format de Transcription de Session

Les transcriptions de session sont stockées sous forme de fichiers JSONL (JSON Lines), avec chaque ligne représentant un message ou un événement :

{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Bonjour Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"Bonjour ! Comment puis-je vous aider ?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"État initial","id":"chk456"}

Chaque ligne du fichier JSONL représente :

• Messages utilisateur : Entrée de l’utilisateur
• Messages assistant : Réponses de Claude
• Points de contrôle : États sauvegardés dans la conversation (par exemple, après avoir terminé une tâche)
• Utilisation d’outils : Enregistrements de quand les outils ont été invoqués et leurs résultats

Cycle de Vie des Sessions

Création et Initialisation

Quand une session démarre, le SDK effectue plusieurs étapes d’initialisation :

1. Générer l’ID de Session : Crée un identifiant unique pour la session
2. Créer le Répertoire de Projet : Configure l’emplacement de stockage spécifique au projet
3. Initialiser le Fichier de Transcription : Crée un fichier JSONL vide pour la conversation
4. Stocker les Métadonnées Initiales : Enregistre l’heure de création de la session et la configuration

Obtenir l’ID de Session

L’ID de session est fourni dans le message système initial lorsque vous démarrez une conversation. Vous pouvez le capturer pour une utilisation ultérieure :

TypeScript

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

let sessionId: string | undefined

const response = query({
  prompt: "Aidez-moi à construire une application web",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // Le premier message est un message d'init système avec l'ID de session
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session démarrée avec l'ID : ${sessionId}`)
    // Vous pouvez sauvegarder cet ID pour une reprise ultérieure
  }
  
  // Traiter les autres messages...
  console.log(message)
}

// Plus tard, vous pouvez utiliser le sessionId sauvegardé pour reprendre
if (sessionId) {
  const resumedResponse = query({
    prompt: "Continuer là où nous nous sommes arrêtés",
    options: {
      resume: sessionId
    }
  })
}

Persistance de l’État de Session

Le SDK persiste automatiquement l’état de session sur le disque :

• Après chaque échange de messages : La transcription est mise à jour
• Lors d’invocations d’outils : L’utilisation d’outils et les résultats sont enregistrés
• Aux points de contrôle : Les états importants de conversation sont marqués
• À la fin de session : L’état final est sauvegardé

Reprise de Session

Le SDK prend en charge la reprise de sessions à partir d’états de conversation précédents, permettant des flux de travail de développement continus.

Reprendre à partir de Fichiers de Session

TypeScript

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

// Reprendre une session précédente en utilisant son ID
const response = query({
  prompt: "Continuer l'implémentation du système d'authentification là où nous nous sommes arrêtés",
  options: {
    resume: "session-xyz", // ID de session de la conversation précédente
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// La conversation continue avec le contexte complet de la session précédente
for await (const message of response) {
  console.log(message)
}

Gestion d’Erreurs et Récupération

Gestion des Sessions Interrompues

TypeScript

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

// Vérifier si une session a été interrompue
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 session a été interrompue. Prête pour la reprise...')
    
    // Le SDK gère le chargement de la transcription en interne
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// Reprendre une session interrompue
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "Continuons là où nous nous sommes arrêtés",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}

Le système de gestion de session du SDK Claude Code fournit une base robuste pour maintenir l’état des conversations et permettre la reprise transparente des tâches de développement, le tout grâce à une approche simple basée sur des fichiers qui ne nécessite aucune infrastructure externe.