# Usage-Optimierung — Befunde und Messmethodik Stand: 2026-08-05. Ausgangsfrage: Wie lassen sich autonome ClaudeDo-Agents token-effizient betreiben? Abrechnung läuft über **Abo-Session-Limits, nicht über die API** — relevant ist roher Token-Verbrauch gegen 5h-/7d-Fenster, nicht Geld. Dieses Dokument ist bewusst kompakt gehalten. Was eine Session früh in den Prefix lädt, wird mit jeder weiteren Nachricht multipliziert (siehe Befund 5) — ein 30k-Handover-Dokument würde das Problem reproduzieren, das es beschreibt. --- ## 1. Verbrauchsstruktur Gemessen über alle Transcripts unter `C:\Users\mika.kuns\.claude\projects`. | Posten | Roh-Token | Anteil | |---|---:|---:| | Cache-Read | 3.118.025.644 | 95,6 % | | Cache-Write | 140.783.227 | 4,3 % | | Output | 22.466.702 | 0,7 % | | Input frisch | 141.496 | 0,0 % | **Kontext-Resend = 99,3 % des Rohverbrauchs.** Auch unter API-Preisgewichtung (read 0,1× / write 1,25× / out 5×) bleibt es bei 81,3 %. Die Rangfolge ist gegen jede plausible Gewichtung robust. Verstärkung: ~3,6 Mio einzigartiger Inhalt → 1,59 Mrd abgerechnete Prompt-Token in ClaudeDo-Sessions. **Jeder Kontext-Token wird im Schnitt ~425× erneut abgerechnet.** ## 2. Scope-Split — wer verbraucht | Scope | Roh-Token | Anteil | |---|---:|---:| | INTERAKTIV (Mikas eigene Sessions) | 2.690.028.785 | **81,6 %** | | AGENT (ClaudeDo-Runs) | 606.222.055 | **18,4 %** | Interaktiv nach Modell: opus-4-8 33,0 % · opus-5 28,5 % · sonnet-5 14,0 % · fable-5 5,2 %. Agent-Runs fahren überwiegend sonnet-5 — der Default greift, die Modelldisziplin auf Agent-Seite ist in Ordnung. **Konsequenz:** ClaudeDo-Optimierung adressiert maximal 18 % des Limits. Der größere Block sind die eigenen Opus-Sessions. ## 3. Session-Länge ist der Treiber Verbrauch ≈ Nachrichten × Ø-Kontext, und der Kontext wächst mit den Nachrichten → **quadratisch**. Eine Session in k Teile schneiden bringt grob 1/k. Interaktiv: **Top 20 von 255 Sessions = 55,9 % des Verbrauchs.** | Roh-Token | Msgs | Ø Kontext | Modell | |---:|---:|---:|---| | 199.516.097 | 716 | 278.653 | opus-4-8 | | 138.020.247 | 440 | 313.682 | opus-5 | | 123.586.522 | 463 | 266.925 | opus-4-8 | ## 4. Was den Kontext füllt | Tool | Anteil (Agent) | Anteil (interaktiv) | |---|---:|---:| | Read | 59,8 % | 68,2 % | | Bash | 16,3 % | 15,4 % | | Grep | 8,3 % | 5,2 % | Read ohne `offset`/`limit`: **57 % (Agent) / 62 % (interaktiv)**. Re-Reads derselben Datei in derselben Session: 18 % der Read-Calls. Subagent-Nutzung: nur 40 Calls bei 1.325 Reads (Agent-Seite) — die Kontext-Firewall ist praktisch ungenutzt. Interaktiv sind Subagent-Sessions dagegen 20 % des Verbrauchs. Teuerste Read-Ziele sind God-Files: `TasksIslandViewModel.cs` (1121 Z.), `ExternalMcpService.cs` (1002 Z.), `WorkerHub.cs` (979 Z.). ## 5. Prefix-Größe × Nachrichtenzahl schlägt alles Fallstudie an der Analyse-Session selbst (136 Msgs, 43.492.835 Roh-Token): ``` msg 1 : 39.914 msg 3 : 273.822 (+233.908) <-- claude-api-Skill geladen msg 136: 380.327 ``` Der Skill in Nachricht 3 wurde danach 136× mitgelesen: **31,8 Mio Token = 73 % der Session**. Zum Vergleich: **alle tool_results zusammen = 21.600 Token (0,05 %)**. Discovery ist praktisch gratis, wenn man aggregiert statt Dateien dumpt. Teuer ist ausschließlich, was früh und groß in den Prefix wandert. Derselbe Block in Nachricht 120 geladen hätte ein Zwanzigstel gekostet. ## 6. Amortisation von Planungssessions | Posten | Token | |---|---:| | Analyse-Session gesamt | 43,5 Mio | | davon vermeidbarer Prefix-Ballast | −31,8 Mio | | echte Planungsleistung | ≈ 11,7 Mio | Gegenrechnung: **10 von 37 Tasks brauchten einen Retry (27 %)**, 13 von 54 Runs sind Wiederholungen. Ein Agent-Run liegt im Schnitt bei ~11 Mio Roh-Token — ein vermiedener Retry spart also grob eine ganze Planungssession. Dazu ersparte Rediscovery: ein Fund von ~8k Token, den ein Agent in Turn 10 eines 60-Turn-Runs selbst machen müsste, wird danach ~50× mitgelesen = ~400k pro Fund. **Fazit: gründliche Planung rechnet sich — aber nur bei schlankem Prefix.** --- ## Was NICHT hilft (geprüft und verworfen) - **`--effort` senken.** Thinking ist 12.536 Token über alle interaktiven Sessions = **0,00 %** des Verbrauchs. Effort zu senken spart nichts und kostet Qualität. Endgültig erledigt. - **Skill-Trigger entschärfen.** Der `claude-api`-Skill kostete in einer Session 73 % — feuerte aber nur **2× in 3 Wochen** (2026-07-14, 2026-08-05). Erwarteter Nutzen vernachlässigbar, Risiko (Antworten aus veraltetem Prior) real. Er hat sich in dieser Session sogar bezahlt gemacht: der Hinweis, dass `input_tokens` nur der uncached Rest ist, hat den Accounting-Bug aufgedeckt. - **God-Files splitten.** Eigenes Risiko; Read-Disziplin entschärft das Symptom billiger. ## Offene Hebel — noch nicht untersucht - Interaktive Session-Hygiene: ab wann lohnt `/clear`, messbar an Ø-Kontext? - Modellrouting interaktiv (opus-4-8 + opus-5 = 61,5 % des Accounts). - Subagent-Ökonomie: Firewall-Nutzen gegen Eigenverbrauch (20 % interaktiv). - MCP-Tool-Definitionen im Prefix: Umfang bei ~200 deferred Tools nicht gemessen. - Kalibrierung der tatsächlichen Limit-Gewichtung gegen die Rohtoken-Zahlen (braucht `/usage`-Ausgabe; der OAuth-Endpoint ist für Claude nicht zugänglich, weil `~/.claude/.credentials.json` hart blockiert ist). --- ## Messmethodik (reproduzierbar) Datenquelle: `C:\Users\mika.kuns\.claude\projects\**\*.jsonl`, ein Record je Message, Verbrauch in `message.usage`. ```python raw = (u.get('input_tokens',0) + u.get('output_tokens',0) + u.get('cache_read_input_tokens',0) + u.get('cache_creation_input_tokens',0)) ``` Kontextgröße einer Message = `input_tokens + cache_read + cache_write` (ohne Output). Der Verlauf über die Session zeigt Prefix-Sprünge. ### Fallstricke 1. **Scope-Filter.** NICHT nach Pfadname `claudedo` filtern — das zieht interaktive Sessions im ClaudeDo-Repo mit rein und verfälscht den Split massiv (53 % statt korrekt 18,4 %). Agent-Runs erkennt man an `claudedo-worktrees` oder `sandbox` im Projektordner, so wie es `TranscriptUsageReader` macht. 2. **``-Messages** überspringen — keine echten API-Calls. 3. **`task_runs.tokens_in` ist unbrauchbar** — liest nur `input_tokens`, also den uncached Rest. Lag bei einer 79-Mio-Token-Session bei 200 (Faktor ~400.000). `tokens_out` zusätzlich 3,8× zu niedrig. Siehe Task `38394081`. 4. **In Bash absolute Pfade verwenden** — `$HOME`/`~` zeigt auf dieser Maschine auf das P:-Laufwerk, nicht auf `C:\Users\mika.kuns`. 5. **DB nie direkt lesen** während die App läuft — Kopie ziehen (`todo.db` + `todo.db-wal`). 6. **Grundrate prüfen, bevor ein Hebel empfohlen wird.** Ein teurer Einzelfall ist kein Muster (siehe Skill-Trigger oben). --- ## Abgeleitete Tasks (Liste „Claude do") Empfohlene Reihenfolge: | # | ID | Titel | |---|---|---| | 1 | `1b599d67` | Prompt-Dateien frieren Default ein — `SuggestImprovement`/`AskUser` tot | | 2 | `38394081` | Limit-Verbrauch pro Run sichtbar machen (Cache-Token in `task_runs`) | | 3 | `0d0aa8b0` | Read-Disziplin + Explorer-Subagent im System-Prompt | | 4 | `2de2f008` | `max_turns` deckeln (Ceiling, Defaults, UI-Warnung) | | 5 | `87105f5e` | UsageGate: Parallelität stufenweise drosseln | (1) zuerst, weil es ein echter Funktionsbug ist und Voraussetzung dafür, dass (3) den Nutzer überhaupt erreicht. (2) als Nächstes, weil ohne korrektes Accounting nichts messbar ist. ### Ist-Zustand zum Zeitpunkt der Analyse - `app_settings`: `default_model` = sonnet, `default_max_turns` = 100, `max_parallel_executions` = 3, `model_presets` = **null** (fällt auf Defaults zurück: haiku 20 / sonnet 30 / opus 40 / fable 25 — greifen faktisch nie). - 15 Tasks überschreiben `max_turns` nach oben: 10× auf 100, 5× auf 200. - UsageGate existiert bereits: 5h @ 80 %, 7d @ 90 % (Migration `20260805074906_AddUsageGateAndRunModel`, dieselbe Migration hat auch die `model`-Spalte auf `task_runs` gebracht). - `~/.todo-app/prompts/system.md` stammt vom 2026-06-04 und weicht vom `SystemDefault` in `PromptFiles.cs` ab; `agent.md` und `planning.md` dort sind verwaiste Reste eines alten Namensschemas.