​
Session-Verwaltung

Das Claude Code SDK bietet Session-Verwaltungsfunktionen für die Handhabung von Konversationszuständen, Persistierung und Wiederaufnahme. Dieser Leitfaden behandelt, wie Sessions erstellt, verwaltet, in Dateien persistiert und innerhalb des SDK wiederaufgenommen werden.

​
Session-Architektur

Das Claude Code SDK implementiert ein dateibasiertes Session-Verwaltungssystem, das Konversationspersistierung und Zustandswiederherstellung handhabt.

​
Session-Dateistruktur

Sessions werden im lokalen Dateisystem in einem strukturierten Format persistiert: 
~/.config/claude/
├── sessions/
│   └── sessions.json          # Session-Metadaten und -Zustand
└── projects/
    └── {project-hash}/
        └── {session-id}.jsonl # Session-Transkript

​
Session-Metadatenformat

Die sessions.json-Datei speichert Metadaten über alle Sessions: 
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
  }
}

​
Session-Transkriptformat

Session-Transkripte werden als JSONL (JSON Lines)-Dateien gespeichert, wobei jede Zeile eine Nachricht oder ein Ereignis darstellt: 
{"type":"user","uuid":"abc123","timestamp":"2024-01-01T10:00:00Z","message":{"content":"Hallo Claude"}}
{"type":"assistant","uuid":"def456","parentUuid":"abc123","timestamp":"2024-01-01T10:00:01Z","message":{"content":[{"type":"text","text":"Hallo! Wie kann ich helfen?"}]}}
{"type":"checkpoint","sessionId":"session123","commit":"a1b2c3d","timestamp":"2024-01-01T10:00:02Z","label":"Anfangszustand","id":"chk456"}
Jede Zeile in der JSONL-Datei repräsentiert:
  • Benutzernachrichten: Eingaben vom Benutzer
  • Assistentennachrichten: Antworten von Claude
  • Checkpoints: Gespeicherte Zustände in der Konversation (z.B. nach Abschluss einer Aufgabe)
  • Tool-Verwendung: Aufzeichnungen darüber, wann Tools aufgerufen wurden und deren Ergebnisse

​
Session-Lebenszyklus

​
Erstellung und Initialisierung

Wenn eine Session startet, führt das SDK mehrere Initialisierungsschritte durch:
  1. Session-ID generieren: Erstellt eine eindeutige Kennung für die Session
  2. Projektverzeichnis erstellen: Richtet den projektspezifischen Speicherort ein
  3. Transkriptdatei initialisieren: Erstellt eine leere JSONL-Datei für die Konversation
  4. Anfangsmetadaten speichern: Zeichnet Session-Erstellungszeit und -Konfiguration auf

​
Abrufen der Session-ID

Die Session-ID wird in der anfänglichen Systemnachricht bereitgestellt, wenn Sie eine Konversation starten. Sie können sie für spätere Verwendung erfassen: 
import { query } from "@anthropic-ai/claude-code"

let sessionId: string | undefined

const response = query({
  prompt: "Hilf mir beim Erstellen einer Webanwendung",
  options: {
    model: "claude-sonnet-4-20250514"
  }
})

for await (const message of response) {
  // Die erste Nachricht ist eine System-Init-Nachricht mit der Session-ID
  if (message.type === 'system' && message.subtype === 'init') {
    sessionId = message.session_id
    console.log(`Session gestartet mit ID: ${sessionId}`)
    // Sie können diese ID für spätere Wiederaufnahme speichern
  }
  
  // Andere Nachrichten verarbeiten...
  console.log(message)
}

// Später können Sie die gespeicherte sessionId verwenden, um fortzufahren
if (sessionId) {
  const resumedResponse = query({
    prompt: "Dort weitermachen, wo wir aufgehört haben",
    options: {
      resume: sessionId
    }
  })
}

​
Session-Zustandspersistierung

Das SDK persistiert automatisch den Session-Zustand auf die Festplatte:
  • Nach jedem Nachrichtenaustausch: Das Transkript wird aktualisiert
  • Bei Tool-Aufrufen: Tool-Verwendung und -Ergebnisse werden aufgezeichnet
  • An Checkpoints: Wichtige Konversationszustände werden markiert
  • Bei Session-Ende: Der finale Zustand wird gespeichert

​
Session-Wiederaufnahme

Das SDK unterstützt die Wiederaufnahme von Sessions aus vorherigen Konversationszuständen und ermöglicht kontinuierliche Entwicklungsworkflows.

​
Wiederaufnahme aus Session-Dateien

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

// Eine vorherige Session mit ihrer ID wiederaufnehmen
const response = query({
  prompt: "Die Implementierung des Authentifizierungssystems dort fortsetzen, wo wir aufgehört haben",
  options: {
    resume: "session-xyz", // Session-ID aus vorheriger Konversation
    model: "claude-sonnet-4-20250514",
    allowedTools: ["Read", "Edit", "Write", "Glob", "Grep", "Bash"]
  }
})

// Die Konversation wird mit vollem Kontext aus der vorherigen Session fortgesetzt
for await (const message of response) {
  console.log(message)
}

​
Fehlerbehandlung und Wiederherstellung

​
Behandlung unterbrochener Sessions

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

// Prüfen, ob eine Session unterbrochen wurde
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('Session wurde unterbrochen. Bereit für Wiederaufnahme...')
    
    // Das SDK handhabt das Laden des Transkripts intern
    return {
      canResume: true,
      sessionId: sessionId
    }
  }
  
  return { canResume: false }
}

// Eine unterbrochene Session wiederaufnehmen
const resumeInterrupted = async (sessionId: string) => {
  const status = await checkSessionStatus(sessionId)
  
  if (status.canResume) {
    const response = query({
      prompt: "Lass uns dort weitermachen, wo wir aufgehört haben",
      options: {
        resume: status.sessionId
      }
    })
    
    for await (const message of response) {
      console.log(message)
    }
  }
}
Das Session-Verwaltungssystem des Claude Code SDK bietet eine robuste Grundlage für die Aufrechterhaltung des Konversationszustands und ermöglicht nahtlose Wiederaufnahme von Entwicklungsaufgaben, alles durch einen einfachen dateibasierten Ansatz, der keine externe Infrastruktur erfordert.