06 — Sessions & Bootstrap — Claw Code How-To

Grundlagen

Was ist eine Session?

Der zentrale Zustandscontainer für alle Agent-Interaktionen.

Kernkonzept 5 Min

Eine Session (Sitzung) ist das Herzstück des Claw Code Systems. Sie speichert alle Informationen, die während einer Interaktion mit dem KI-Agenten anfallen — vom ersten Prompt bis zur finalen Antwort.

Komponenten einer Session

Komponente	Beschreibung	Beispiel
Session-ID	Eindeutiger Identifikator	`sess_abc123xyz`
Transkript	Chronologische Nachrichtenhistorie	User-Prompts, Assistant-Antworten
Workspace-Kontext	Informationen über die Umgebung	Pfad, Dateianzahl, Git-Status
Metadaten	Zusätzliche Session-Informationen	Erstellungszeit, letzte Aktivität
Budget-Tracker	Token-Verbrauch überwachen	Input/Output/Total

💡

Vergleich: Session vs. Conversation

Eine Conversation ist nur das Transkript (die Nachrichten). Eine Session enthält zusätzlich den Workspace-Kontext, Metadaten und Persistenz-Informationen. Sessions sind "Conversations plus Kontext".

Die 4 Phasen

Session-Lebenszyklus

Create → Process → Compact → Persist → Load

Kernkonzept 10 Min

Der Lebenszyklus einer Session durchläuft vier klar definierte Phasen. Jede Phase hat einen spezifischen Zweck und spezifische Methoden.

Die 4 Phasen im Überblick

🆕

1. Create — Sitzung erstellen

Eine neue Session wird aus dem Workspace-Kontext initialisiert. Der QueryEnginePort sammelt Informationen über das aktuelle Arbeitsverzeichnis und erzeugt eine eindeutige Session-ID.

QueryEnginePort.from_workspace()

⚙️

2. Process — Prompt verarbeiten

Der Benutzer sendet einen Prompt. Das System routed ihn an passende Befehle und Tools, führt die Aktionen aus und aktualisiert das Transkript mit der Antwort.

submit_message() → route_prompt()

🗜️

3. Compact — Kompaktierung

Wenn das Transkript zu groß wird (Token-Limit erreicht), wird es automatisch komprimiert. Ältere Nachrichten werden zusammengefasst oder entfernt, wichtige Kontextinformationen bleiben erhalten.

compact_messages_if_needed()

💾

4. Persist — Speichern & Laden

Die Session wird in .port_sessions/ persistiert und kann später über die Session-ID wieder geladen werden. Das ermöglicht Unterbrechungen und Fortsetzungen langer Arbeitsabläufe.

flush-transcript → load-session

Visueller Ablauf

WorkspaceErkennen

→

Create Sessionsess_xxx

→

ProcessPrompt → Routing

↓

LoadWiederherstellen

←

Persist.port_sessions/

←

CompactToken-Limit?

Ausführung

Bootstrap ausführen

Eine vollständige Session mit einem einzigen Befehl starten.

CLI 5 Min

Der bootstrap-Befehl ist der Haupteinstiegspunkt für vollständige Agent-Sitzungen. Er kombiniert Session-Erstellung, Prompt-Routing und Ausführung in einem Schritt.

Bootstrap-Grundbefehl

bash

# Vollständige Session starten
$ python3 -m src.main bootstrap "Analysiere die Codebasis"

╔════════════════════════════════════════════════╗
║ Claw Code — Session-Bericht ║
╚════════════════════════════════════════════════╝

Session-ID: sess_abc123xyz
Commands matched: 5
Tools matched: 3
Status: success
Duration: 1.2s

Was passiert beim Bootstrap?

Workspace-Erkennung — Das System analysiert das aktuelle Verzeichnis
Session-Initialisierung — Eine neue Session mit eindeutiger ID wird erstellt
Prompt-Routing — Der Prompt wird tokenisiert und an passende Befehle/Tools gerouted
Ausführung — Die Matches werden ausgeführt und Ergebnisse generiert
Transkript-Update — Die Interaktion wird im Session-Transkript gespeichert

⚠️

Wichtig

Der Bootstrap-Befehl erstellt eine neue Session. Wenn du eine bestehende Session fortsetzen möchtest, verwende load-session (siehe unten).

Bootstrap mit Optionen

# Mit benutzerdefiniertem Limit für Matches
$ python3 -m src.main bootstrap "Erstelle Tests" --limit 10

# Strukturierte JSON-Ausgabe
$ python3 -m src.main bootstrap "Refaktoriere" --json

Persistenz

Session speichern (flush-transcript)

Das Transkript persistieren und eine Session-ID erhalten.

Persistenz 5 Min

Das flush-transcript-Kommando speichert die aktuelle Session auf der Festplatte. Dies ist essenziell, um Arbeit zu sichern und später fortzusetzen.

Flush-Transcript Befehl

bash

# Aktuelle Session speichern
$ python3 -m src.main flush-transcript "Meine Analyse-Session"

💾 Transkript gespeichert
Session-ID: sess_abc123xyz
Pfad: .port_sessions/sess_abc123xyz.json
Nachrichten: 12
Größe: 4.2 KB

Was wird gespeichert?

Feld	Beschreibung
`session_id`	Eindeutige Session-Identifikation
`title`	Vom Benutzer vergebener Titel
`messages`	Alle Nachrichten im Transkript
`workspace_context`	Pfad, Dateien, Git-Status
`created_at`	Zeitstempel der Erstellung
`updated_at`	Zeitstempel der letzten Änderung
`metadata`	Zusätzliche Session-Informationen

Speicherort

Sessions werden im Verzeichnis .port_sessions/ im Projekt-Root gespeichert. Jede Session ist eine separate JSON-Datei:

$ ls -la .port_sessions/

sess_abc123xyz.json
sess_def456uvw.json
sess_ghi789rst.json

✅

Best Practice

Gib deinen Sessions aussagekräftige Titel mit flush-transcript. So findest du später schnell die richtige Session wieder.

Wiederherstellung

Session laden (load-session)

Eine gespeicherte Session wiederherstellen und fortsetzen.

Persistenz 5 Min

Mit load-session kannst du eine zuvor gespeicherte Session wiederherstellen und genau dort weitermachen, wo du aufgehört hast.

Load-Session Befehl

bash

# Session anhand ID laden
$ python3 -m src.main load-session sess_abc123xyz

📂 Session geladen
Titel: Meine Analyse-Session
Nachrichten: 12
Erstellt: 2026-04-01 14:30
Status: Bereit für neue Nachrichten

Ablauf beim Laden

JSON-Datei lesen

Das System öffnet .port_sessions/sess_xxx.json und parst die Session-Daten.

Session-Objekt rekonstruieren

Ein QueryEnginePort-Objekt wird mit allen gespeicherten Daten initialisiert.

Workspace-Kontext validieren

Das System prüft, ob sich der Workspace seit dem Speichern verändert hat.

Bereit für neue Nachrichten

Die Session ist nun aktiv und kann neue Prompts entgegennehmen.

Sessions auflisten

Um alle verfügbaren Sessions zu sehen:

$ ls .port_sessions/

# oder detaillierter:
$ python3 -m src.main list-sessions

Referenz

Session-ID erklärt

Aufbau und Bedeutung der Session-Identifikation.

Referenz 2 Min

Die Session-ID ist der Schlüssel zur Wiederherstellung deiner Arbeit. Sie wird automatisch generiert und ist innerhalb deines Systems eindeutig.

Session-ID Format

sess_abc123xyz

Aufbau der Session-ID

Teil	Beschreibung	Beispiel
Präfix	Identifiziert den Typ	`sess_` = Session
Body	Zufällige alphanumerische Zeichen	`abc123xyz`

Wann wird eine Session-ID generiert?

Bootstrap — Neue Session wird erstellt
Flush-Transcript — Session wird erstmalig persistiert
Manuelle Erstellung — Über die API/Programmatisch

Session-ID speichern

Notiere dir die Session-ID nach dem Bootstrap oder Flush-Transcript. Sie wird im Terminal angezeigt:

# Kopiere die ID direkt aus der Ausgabe
Session-ID: sess_abc123xyz

# Oder speichere sie in einer Variable
$ SESSION_ID=$(python3 -m src.main bootstrap "Test" | grep "Session-ID" | awk '{print $2}')

🔑

Session-ID = Wiederherstellungsschlüssel

Ohne die Session-ID kannst du eine persistierte Session nicht wieder laden. Sie ist das einzige Bindeglied zwischen Speichern und Laden.

Vollständiges Beispiel

bash — Vollständiger Workflow

# 1. Neue Session starten
$ python3 -m src.main bootstrap "Analysiere src/"
Session-ID: sess_abc123xyz

# 2. Weitere Interaktionen...
# (Prompts senden, Ergebnisse erhalten)

# 3. Session speichern
$ python3 -m src.main flush-transcript "Code-Analyse vom 3.4."
Session-ID: sess_abc123xyz

# 4. Später: Session wiederherstellen
$ python3 -m src.main load-session sess_abc123xyz
📂 Session "Code-Analyse vom 3.4." geladen

# 5. Weitermachen wo du aufgehört hast
$ python3 -m src.main bootstrap "Fahre mit der Analyse fort"

✓

Abschluss

Zusammenfassung

Die wichtigsten Befehle im Überblick.

Befehl	Zweck	Wichtige Ausgabe
`bootstrap "Prompt"`	Neue Session erstellen & Prompt verarbeiten	Session-ID
`flush-transcript "Titel"`	Session persistieren	Session-ID, Pfad
`load-session ID`	Gespeicherte Session laden	Session-Status

🎉

Abschnitt 06 abgeschlossen!

Du verstehst nun den Session-Lebenszyklus, kannst Sessions erstellen, speichern und laden. Damit hast du die Kernkonzepte der Claw Code Persistenz beherrscht.

← Zurück zum How-To