07 — Turn-Loops & Budget-System

Grundlagen

Was sind Turn-Loops?

Der Unterschied zwischen einem einzelnen Turn und einer Multi-Turn-Schleife - das Herzstueck agentenartiger Verarbeitung.

Kernkonzept 10 Min

Definition: Turn vs. Turn-Loop

Ein Turn (Durchgang) ist ein einzelner Verarbeitungszyklus im Claw Code System. Ein Turn-Loop fuehrt mehrere Turns nacheinander aus, wobei jeder Turn auf dem Ergebnis des vorherigen aufbaut.

Prompt

→

Routing

→

Ausfuehrung

→

Antwort

Ein einzelner Turn

Die Iterations-Logik

Turn-Loops ermoeglichen es dem System, komplexe Aufgaben Schritt fuer Schritt zu bearbeiten:

Turn 1 - Initialer Prompt, erstes Routing, Basisanalyse
Turn 2 - Aufbauend auf Turn 1, vertiefte Analyse
Turn 3 - Verfeinerung der Ergebnisse, Korrekturen
Turn n - Finale Zusammenfassung oder bis Stop-Condition erreicht

💡

Vorteil von Turn-Loops

Anstatt alles auf einmal zu versuchen, bricht der Agent komplexe Aufgaben in ueberschaubare Schritte auf. Jeder Turn kann sich auf einen Aspekt konzentrieren und das Gesamtergebnis iterativ verbessern.

Praxis

Turn-Loop ausfuehren

Den turn-loop Befehl verwenden und seine Ausgabe interpretieren.

Kern 5 Min

Der turn-loop Befehl

Der turn-loop Befehl startet eine Multi-Turn-Verarbeitung mit automatischer Iteration.

bash

# Standard: bis zu 5 Turns
$ python3 -m src.main turn-loop "Analysiere die Codebasis"

Turn-Loop gestartet...
Turn 1/5: Initialanalyse
  Commands: [analyze, grep, ls]
  Tools: [Read, Glob]
Turn 2/5: Vertiefung
  Commands: [refactor, diff]
  Tools: [Read, Write]
...
Turn-Loop abgeschlossen nach 5 Turns

Was passiert intern?

Session-Initialisierung

Ein QueryEnginePort wird erstellt und mit dem Workspace-Kontext initialisiert.

Prompt-Routing

Der Prompt wird tokenisiert und die besten Befehle/Tools werden ueber route_prompt() ermittelt.

Ausfuehrung simulieren

Die gematchten Befehle/Tools werden simuliert (keine echte Ausfuehrung im Port).

Ergebnis als Kontext

Das Ergebnis wird dem naechsten Turn als zusaetzlicher Kontext hinzugefuegt.

Iteration oder Abbruch

Pruefung der Stop-Conditions: Budget ueberschritten? Max-Turns erreicht? Ziel erfuellt?

Konfiguration

Optionen & Flags

Steuere das Verhalten des Turn-Loops mit Kommandozeilen-Optionen.

Fortgeschritten 5 Min

--max-turns: Anzahl der Turns begrenzen

Mit --max-turns (oder -m) kannst du festlegen, wie viele Iterationen maximal ausgefuehrt werden.

bash

# Nur 3 Turns ausfuehren
$ python3 -m src.main turn-loop "Refaktoriere den Code" --max-turns 3

# Kurzform
$ python3 -m src.main turn-loop "Analysiere" -m 2

# Unbegrenzte Turns (Vorsicht!)
$ python3 -m src.main turn-loop "Komplexe Aufgabe" --max-turns 0

Wert	Verhalten
`--max-turns 1-100`	Fuehrt genau N Turns aus oder bricht frueher bei Stop-Condition ab
`--max-turns 0`	Kein Limit (nur durch Budget oder andere Stop-Conditions begrenzt)
nicht gesetzt	Standardwert ist 5 Turns

--structured-output: JSON-Ausgabe

Fuer die Weiterverarbeitung in Skripten oder CI/CD-Pipelines kannst du die Ausgabe als JSON formatieren.

bash

# JSON-Ausgabe fuer Weiterverarbeitung
$ python3 -m src.main turn-loop "Analysiere" --structured-output

{
  "turns": 5,
  "session_id": "sess_abc123",
  "commands_used": ["analyze", "grep", "refactor"],
  "tools_used": ["Read", "Glob", "Write"],
  "completed": true,
  "stop_reason": "max_turns_reached"
}

💡

Pro-Tipp

Kombiniere --structured-output mit jq fuer maechtige Pipeline-Operationen:
python3 -m src.main turn-loop "Task" --structured-output | jq '.commands_used'

Alle Optionen im Ueberblick

bash

$ python3 -m src.main turn-loop --help

Usage: turn-loop [PROMPT] [OPTIONS]

Options:
  --max-turns, -m INTEGER  Maximum number of turns (default: 5)
  --structured-output      Output as JSON
  --session-id TEXT        Resume existing session
  --compact-threshold INT  Token threshold for compaction

Architektur

Token-Budget erklaert

Wie das System Token-Verbrauch ueber Turns hinweg verfolgt und verwaltet.

Kern 10 Min

Die drei Budget-Kategorien

Das Budget-System verfolgt den Token-Verbrauch in drei Kategorien:

Kategorie	Beschreibung	Beispiel
Input-Tokens	Tokens im Prompt + Kontext	"Analysiere die Datei main.py"
Output-Tokens	Tokens in der generierten Antwort	Befehlsvorschlaege, Erklaerungen
Total-Budget	Maximale Tokens pro Session	Standard: 100.000 Tokens

Budget-Tracking im Code

Die Budget-Verwaltung erfolgt in der QueryEnginePort Klasse:

# Vereinfachte Darstellung aus runtime.py

class TurnBudget:

    def __init__(self, max_tokens=100_000):

        self.max_tokens = max_tokens

        self.used_input = 0

        self.used_output = 0

    def track_turn(self, input_tokens, output_tokens):

        self.used_input += input_tokens

        self.used_output += output_tokens

    def remaining(self):

        return self.max_tokens - (self.used_input + self.used_output)

Kompaktierung bei Budget-Knappheit

Wenn das Budget knapp wird, wird automatisch kompaktisiert:

bash

Turn 3/10: Budget bei 80%
  - Kompaktierung gestartet
  - Alte Turns werden zusammengefasst
  - Kontext reduziert, Kerninformationen erhalten
Turn 4/10: Weiter mit kompaktem Kontext

⚠

Hinweis zur Simulation

Das Budget-System im Claw Code ist eine Simulation. Es zeigt, wie das originale System Ressourcen verwaltet haette, ohne echte API-Kosten zu verursachen. Die Token-Zahlen sind Schaetzungen basierend auf Wort-Charakter-Verhaeltnissen.

Kontrolle

Stop-Conditions

Wann und warum ein Turn-Loop automatisch stoppt - und wie du das steuerst.

Fortgeschritten 5 Min

Die vier Stop-Conditions

Max-Turns erreicht

Die angegebene maximale Anzahl an Turns wurde ausgefuehrt. Stop-Reason: max_turns_reached

Budget erschoepft

Das Token-Budget wurde ueberschritten oder ist zu knapp fuer weitere Turns. Stop-Reason: budget_exhausted

Ziel erreicht (simuliert)

Das System erkennt, dass die Aufgabe vollstaendig erledigt ist. Stop-Reason: goal_achieved

Fehler oder Abbruch

Ein kritischer Fehler ist aufgetreten oder der Benutzer hat abgebrochen. Stop-Reason: error oder user_cancelled

Stop-Reason in der Ausgabe

Die stop_reason zeigt dir, warum der Loop beendet wurde:

bash

$ python3 -m src.main turn-loop "Test" --max-turns 3 --structured-output | jq '.stop_reason'
"max_turns_reached"

# Budget-Ueberschreitung simulieren
$ python3 -m src.main turn-loop "Sehr langer Prompt..." --max-turns 100
Turn 8: Budget bei 95%
Turn 9: Budget ueberschritten!
Turn-Loop gestoppt. Grund: budget_exhausted

✅

Best Practice

Starte mit niedrigen --max-turns Werten (3-5) fuer neue Aufgaben. Steigere erst, wenn du siehst, dass das System mehr Iterationen braucht, um gute Ergebnisse zu liefern.

Anwendung

Praktisches Beispiel

Eine komplette Analyse-Session mit Turn-Loop von Anfang bis Ende.

Kern 10 Min

Szenario: Code-Refactoring

Du moechtest eine Python-Datei analysieren und verbessern. Das ist eine Aufgabe, die sich perfekt fuer einen Turn-Loop eignet.

Schritt 1: Initialen Turn-Loop starten

bash

$ python3 -m src.main turn-loop "Analysiere src/main.py und schlage Verbesserungen vor" --max-turns 4

=== Turn-Loop gestartet ===

Turn 1/4: Initialanalyse
  Prompt: "Analysiere src/main.py..."
  Routing:
    Command: analyze (Score: 0.92)
    Command: show-command (Score: 0.74)
    Tool: Read (Score: 0.88)
  Status: Datei analysiert, 3 Verbesserungsbereiche identifiziert

Schritt 2: Zwischenergebnisse betrachten

Turn 2/4: Vertiefung der Analyse
  Kontext: 3 Verbesserungsbereiche aus Turn 1
  Routing:
    Command: grep (Score: 0.81)
    Tool: Read (Score: 0.79)
  Status: Code-Muster untersucht, Redundanzen gefunden

Turn 3/4: Refactoring-Vorschlaege
  Kontext: Redundanzen aus Turn 2
  Routing:
    Command: refactor (Score: 0.95)
    Command: diff (Score: 0.67)
  Status: 5 konkrete Refactoring-Schritte erarbeitet

Schritt 3: Finale Zusammenfassung

Turn 4/4: Dokumentation
  Kontext: 5 Refactoring-Schritte aus Turn 3
  Routing:
    Command: summary (Score: 0.89)
  Status: Finale Zusammenfassung erstellt

=== Turn-Loop abgeschlossen ===
Stop-Reason: max_turns_reached
Budget used: 12,450 / 100,000 tokens (12%)
Session-ID: sess_refactor_2024

Session speichern und fortsetzen

bash

# Session speichern
$ python3 -m src.main flush-transcript "Refactoring-Analyse main.py"
Session gespeichert: sess_refactor_2024

# Später fortsetzen
$ python3 -m src.main load-session sess_refactor_2024
Session geladen: 4 Turns im Verlauf

💡

Workflow-Tipp

Nutze Turn-Loops fuer alle Aufgaben, die mehrere Perspektiven erfordern: Code-Review (Sicherheit → Performance → Lesbarkeit), Debugging (Symptom → Ursache → Fix → Test), Dokumentation (Ueberblick → Details → Beispiele).

🎉

Zusammenfassung

Du beherrschst nun Turn-Loops! Du weisst, wie sie funktionieren, wie du sie konfigurierst, wie das Budget-System arbeitet und wann sie stoppen. Probiere es mit deinen eigenen Aufgaben aus.

06 - Sessions & Bootstrap 08 - Permission-System