Claude Code: Tokenverbrauch senken mit Context Mode und Headroom

Um den Tokenverbrauch von Claude Code zu senken, prüfe zuerst, was das Kontextfenster füllt, und halte unnötige Tool-Ausgaben aus dem Gespräch heraus. Beginne mit den Bordmitteln: Probiere Context Mode für die gezielte Verarbeitung von Daten und die Fortsetzung nach einer Kontextverdichtung oder Headroom für die Komprimierung über einen lokalen Proxy. Wenn vor allem aufwendige Überlegungen und wiederholte Fehlversuche den Verbrauch treiben, grenze zunächst die Aufgabe besser ein und überprüfe die Modellwahl.

Stand 2026-10-21 ist 2.1.306 die aktuelle Claude-Code-Version. Die folgende Headroom-Installation legt die Version auf 0.41.0 fest.

Wofür verbraucht Claude Code Tokens?

Prüfe mit /context die Belegung des Kontextfensters und mit /usage den Verbrauch sowie die geschätzten Kosten. Die beiden Befehle beantworten unterschiedliche Fragen.

Frage	Prüfung	Was du daraus erfährst
Warum füllt sich dieses Gespräch?	/context	Wie viel Platz Anweisungen, Nachrichten, Tools und weitere Kontextbestandteile belegen
Was hat diese Sitzung verbraucht?	/usage	Tokenkategorien und geschätzte Sitzungskosten
Nähere ich mich dem Nutzungslimit meines Abos?	Die Tarifinformationen in /usage	Die Auslastung des Abos, getrennt von einer API-Rechnung
Was wurde tatsächlich berechnet?	Die Nutzungsaufzeichnungen deines abrechnenden Anbieters	Gebühren nach dessen Preisen und Abrechnungsregeln

In der aktuellen Claude-Code-Version ist /cost ein Alias für /usage. Der Dollarbetrag ist eine Schätzung; er bedeutet nicht, dass jede im Pro- oder Max-Abo enthaltene Anfrage diese zusätzliche Gebühr verursacht. Die Kostendokumentation von Claude Code erläutert den Unterschied.

Große Logs, Browser-Snapshots, Abhängigkeitsdateien und wiederholte Tool-Ergebnisse können viel Kontext belegen. Frühere Nachrichten fließen ebenfalls in spätere Anfragen ein. Durch Prompt-Caching kann wiederverwendete Eingabe jedoch günstiger sein als neue Eingabe. Deshalb bedeutet 50% weniger sichtbarer Inhalt nicht automatisch eine um 50% niedrigere Rechnung.

Nutze zuerst die eingebauten Möglichkeiten

Wähle die Maßnahme nach der Ursache: gezielte Abfragen bei überladenen Ausgaben, ein neues Gespräch für unabhängige Aufgaben und eine Kontextverdichtung für längere Arbeiten, die du fortsetzen möchtest.

Gib Claude genaue Dateipfade, die Namen fehlgeschlagener Tests und einen konkreten Prüfungsbefehl. Ein einzelnes fehlerhaftes Modul untersuchen zu lassen, verursacht meist weniger unnötige Arbeit, als vor einer kleinen Änderung das gesamte Repository analysieren zu lassen.

Nutze zwischen unabhängigen Aufgaben /clear, nachdem du benötigte Verbrauchswerte notiert hast. Wenn dieselbe Aufgabe weitergeht, verwende /compact mit gezielten Vorgaben, zum Beispiel:

/compact Preserve the current goal, modified files, failing test names, exact errors, and the next verification command.

Diese Verfahren zur Kontextverwaltung sind dokumentiert. Eine Kontextverdichtung erzeugt aber eine Zusammenfassung und kein exaktes Archiv. Halte entscheidende Abnahmekriterien in dauerhaft gespeicherten Projektanweisungen oder Aufgabennotizen fest.

Verdichte den Kontext nicht nach jedem Austausch. Die Verdichtung löst eine Anfrage zur Zusammenfassung aus und ersetzt den Nachrichtenverlauf. Für die nächste Anfrage muss deshalb ein kürzeres Präfix im Cache aufgebaut werden. Häufiges Verdichten kann den eingesparten Kontext durch zusätzliche Arbeit und wiederholten Cache-Aufbau erkaufen.

Bei einfachen Aufgaben und Modellen mit entsprechender Unterstützung kannst du /effort low ausprobieren. Ein niedrigerer Aufwand kann die Modellüberlegungen reduzieren, verkleinert aber kein Log, das ein Tool bereits zurückgegeben hat. Per Befehl gesetzte Änderungen bleiben für das ausgewählte Modell bestehen; stelle nach dem Vergleich daher deine bevorzugte Einstellung wieder her. Die Dokumentation zur Modellkonfiguration beschreibt die unterstützten Einstellungen und Modellaliasse.

Subagents bieten eine weitere eingebaute Möglichkeit zur Trennung: Sie arbeiten in einem eigenen Kontext und geben eine Zusammenfassung zurück. Das entlastet das übergeordnete Gespräch, ihre eigenen Anfragen verbrauchen jedoch weiterhin Tokens.

Context Mode oder Headroom: Was solltest du zuerst ausprobieren?

Wähle Context Mode, wenn sich Daten bereits vor der Rückgabe an Claude reduzieren lassen. Wähle Headroom, wenn vorhandene Tool-Aufrufe über eine Komprimierungsschicht laufen sollen.

Dein Engpass	Zuerst ausprobieren	Was sich ändert
Große Dateien oder Logs, die sich lokal abfragen oder verarbeiten lassen	Context Mode	Claude erhält über Ausführungs- und Suchtools gezielt ausgewählte Ergebnisse
Teile des Aufgabenstands gehen bei der Kontextverdichtung verloren	Context Mode	Hooks für den Sitzungsablauf erfassen Ereignisse und stellen Informationen zur Fortsetzung wieder her
Umfangreiche Ausgaben aus einem bestehenden Tool-Ablauf	Headroom	Ein lokaler Proxy komprimiert geeignete Tool-Inhalte vor dem Weiterleiten der Anfragen
Kurze Aufgaben, deren Verbrauch vor allem durch Überlegungen oder Wiederholungsversuche entsteht	Eingebaute Möglichkeiten zur Eingrenzung, Aufwandsteuerung und Modellwahl	Der Arbeitsumfang sinkt, bevor eine weitere Komponente hinzukommt

Teste immer nur ein Tool gleichzeitig, damit du die Wirkung zuordnen kannst.

Die veröffentlichten Prozentwerte sind nicht direkt vergleichbar. Das Benchmark-Material von Context Mode misst Ausgabebytes für ausgewählte Beispiele. Die Angaben von 21%–57% bei Headroom stammen aus offline erzeugten Tool-Ausgaben mit festgelegtem Zufallsstartwert. Beide Messungen belegen weder eine entsprechende Senkung deiner gesamten Claude-Code-Rechnung noch ersetzen sie die Prüfung, ob die Aufgabe weiterhin korrekt abgeschlossen wird.

Context Mode: Gezielt Ergebnisse statt ganzer Dateien zurückgeben

Context Mode eignet sich, wenn eine lokale Berechnung die Antwort liefern kann, ohne ihre vollständigen Eingabedaten in Claudes Gespräch zu übernehmen. Das Plugin speichert außerdem ausgewählte Sitzungsereignisse in SQLite und nutzt Hooks, um nach einer Kontextverdichtung Informationen zur Fortsetzung wiederherzustellen.

Das aktuelle Paket benötigt Node.js 22.5.0 oder neuer. Prüfe deine Installation in Bash:

claude --version
node --version

Verwende innerhalb von Claude Code die vom Projekt dokumentierte Installation über den Plugin-Marktplatz:

/plugin marketplace add mksglu/context-mode
/plugin install context-mode@context-mode

Starte Claude Code neu und führe anschließend diesen Befehl aus:

/context-mode:ctx-doctor

Der Doctor-Befehl prüft unter anderem Laufzeitunterstützung, Plugin-Registrierung, Hooks und die Suchunterstützung von SQLite. Behebe relevante Fehler, bevor du davon ausgehst, dass das Plugin aktiv ist. Wenn du nur den MCP-Server installierst, erhältst du nicht dieselbe Einbindung in den Sitzungsablauf über Hooks.

Für eine konkrete Prüfung öffnest du ein npm-Projekt mit einer vorhandenen package-lock.json der Version 2 oder Version 3. Bitte Claude, ctx_execute_file mit path: "package-lock.json", language: "javascript" und folgendem Code aufzurufen:

const lock = JSON.parse(FILE_CONTENT);
if (!lock.packages) {
  console.log("This example requires an npm v2/v3 lockfile.");
} else {
  const rows = Object.entries(lock.packages).filter(([path]) => path !== "");
  console.log(JSON.stringify({
    lockfileVersion: lock.lockfileVersion,
    packageEntries: rows.length,
    entriesMarkedDev: rows.filter(([, pkg]) => pkg.dev === true).length
  }, null, 2));
}

Das Tool stellt die Datei über FILE_CONTENT bereit. Erwartet wird ein kleines JSON-Objekt mit den drei angeforderten Feldern statt der vollständigen Lockdatei. Die tatsächlichen Werte hängen von deinem Projekt ab; gezählt werden Einträge in der Lockdatei, nicht eindeutige Paketnamen.

Führe danach diesen Befehl aus:

/context-mode:ctx-stats

Der Statistikbefehl sollte Aktivität von Context Mode anzeigen. Meldet er keine Aufrufe, ist die Nutzung des angeforderten Ausführungswegs noch nicht nachgewiesen. Seine Angaben zur Reduktion der Ausgabe sind keine Berechnung der Rechnungssumme.

Übertrage das Prinzip auf Logs: Ermittle Anzahlen lokal, wähle relevante Fehler aus und gib exakte Auszüge samt Fundstellen zurück. Kleine Quelldateien solltest du weiterhin direkt lesen lassen, wenn Claude den genauen Code benötigt.

Context Mode verwendet Elastic License 2.0. Seine Ausführungsisolation ist zudem keine vollständige Sicherheitssandbox auf Betriebssystemebene: Ausführungstools können Zugriffsrechte auf das Dateisystem erben. Behalte die Berechtigungen und Sandbox-Einstellungen bei, die du normalerweise für von Agents ausgeführte Befehle verwendest.

Headroom: Geeignete Tool-Ausgaben über einen lokalen Proxy komprimieren

Headroom passt zu Abläufen, in denen die normalen Claude-Code-Tools weiterarbeiten sollen, während ein Proxy geeignete Ausgaben reduziert. Das auf Programmieraufgaben ausgerichtete Standardverhalten berücksichtigt auch die Stabilität des Caches. Es verspricht keine Komprimierung jeder Quelldatei oder jeder Anfrage.

Dieses Beispiel verwendet einen API-Schlüssel aus der Anthropic Console. Dadurch entstehen API-Kosten unabhängig von einem Claude-Abo. Vorausgesetzt werden eine vorhandene Installation von uv und Claude Code, kein bereits laufender Headroom-Proxy und keine aktive, widersprüchliche Konfiguration für ein eigenes Gateway oder einen Cloud-Anbieter. Bestehende Unternehmens-Gateways benötigen einen eigenen Integrationsweg.

Installiere das Proxy-Paket in Bash mit festgelegter Version gemäß der Installationsanleitung von Headroom:

uv tool install --python 3.13 "headroom-ai[proxy]==0.41.0"
headroom --version

Die Versionsprüfung sollte 0.41.0 ausgeben. Lies deinen Schlüssel ohne Bildschirmausgabe ein, drücke Enter und starte anschließend den Wrapper:

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
HEADROOM_TELEMETRY=on HEADROOM_BEACON=off headroom wrap claude --code-memory none

Bestätige die Verwendung des eigenen API-Schlüssels, falls Claude danach fragt. Prüfe anschließend mit /status, welche Zugangsdaten und welches Modell aktiv sind. Wenn du den Schlüssel zuvor abgelehnt hast, beschreibt Claudes Authentifizierungsdokumentation die Einstellung „Use custom API key“ unter /config.

Der Wrapper startet einen lokalen Proxy oder verwendet einen bestehenden, startet Claude über diesen Proxy und registriert den MCP-Server von Headroom zum Nachladen von Inhalten in der Claude-Code-Konfiguration. --code-memory none überspringt die zusätzliche Serena-Integration; das Nachladen über Headroom bleibt verfügbar. Ergänze in dieser Anleitung nicht --no-mcp: Damit entfernst du den Abrufweg, der zu den Markierungen komprimierter Inhalte gehört. Die Optionen sind in der Wrapper-Implementierung von 0.41.0 definiert.

Die Umgebungsvariablen aktivieren die lokale Telemetrieerfassung und deaktivieren deren optionalen Upload-Beacon. Modellanfragen werden weiterhin an den konfigurierten Anbieter gesendet.

Notiere die beim Start ausgegebene Proxy-Adresse. Üblicherweise wird Port 8787 verwendet, der Wrapper kann aber einen anderen verfügbaren Port wählen. Ersetze den Port bei Bedarf im folgenden Aufruf in einem zweiten Bash-Terminal:

curl -fsS http://127.0.0.1:8787/health
curl -fsS http://127.0.0.1:8787/stats

Gib dem über den Wrapper gestarteten Claude nun eine klar begrenzte Aufgabe mit einer vorhandenen, umfangreichen test.log: Er soll die fehlgeschlagenen Tests ohne Duplikate auflisten und für jeden den ersten exakten Fehler zitieren, ohne Dateien zu ändern. Rufe nach Abschluss erneut /stats ab.

Ein erfolgreicher Health-Check belegt, dass der Proxy läuft. Steigt requests.total, erreichen abgeschlossene Anfragen seine Verbrauchserfassung. Prüfe requests.failed und requests.rate_limited getrennt davon. Die Metrikdokumentation erläutert diese Felder. Keine Einsparung bei einer kurzen oder vor Komprimierung geschützten Nutzlast belegt noch keinen Routingfehler.

Wenn die Authentifizierung fehlschlägt, prüfe vor einem erneuten Versuch widersprüchliche Werte für ANTHROPIC_AUTH_TOKEN und ANTHROPIC_BASE_URL sowie die Anbietereinstellungen. Wenn keine Anfragen erscheinen, prüfe den tatsächlich ausgegebenen Port und den Verbindungsweg der gestarteten Sitzung.

Headrooms Mechanismus zum Komprimieren, Zwischenspeichern und Nachladen kann aufbewahrte Originale abrufen, wenn Claude ausgelassene Details benötigt. Das Nachladen verursacht zusätzliche Arbeit, und die Aufbewahrungsdauer ist begrenzt. Ist ein Original nicht mehr verfügbar, greife auf die Quelldatei zurück oder führe den Befehl erneut aus.

Beende den über den Wrapper gestarteten Claude. Bereinige den Versuch anschließend im ursprünglichen Terminal, im selben Projekt und mit dem tatsächlichen Port:

headroom unwrap claude --port 8787
unset ANTHROPIC_API_KEY

Unwrap entfernt die von Headroom verwaltete Einrichtung und versucht, den zugehörigen Proxy zu beenden. Das Entfernen der Umgebungsvariable löscht den für diesen Versuch exportierten API-Schlüssel aus der Shell-Umgebung. Prüfe /status, bevor du zu deiner üblichen Authentifizierung zurückkehrst.

Nutze günstigere Modelle für klar begrenzte Teilaufgaben

Setze ein günstigeres Modell für Aufgaben ein, deren Ergebnis sich mit wenig Aufwand prüfen lässt, etwa das Extrahieren von Fehlern aus einem bereitgestellten Log. Das verändert den Preis der Arbeit, garantiert aber keinen geringeren Tokenverbrauch.

Lege als Vergleich auf Basis der Bordmittel die Datei .claude/agents/log-summary.md an:

---
name: log-summary
description: Summarize supplied test logs and identify failing tests.
model: haiku
tools: Read, Grep, Glob
maxTurns: 6
---

Read only the log paths supplied in the task.
Return failing test names, exact error excerpts, and file or line references.
Report uncertainty and missing evidence.
Do not modify files.

Starte Claude Code nach dem Anlegen des Agents-Verzeichnisses neu. Rufe den Subagent anschließend mit einem vorhandenen Log auf:

Use log-summary to inspect ./test.log and return the first failing test and its exact error. Stop after the summary.

Prüfe während der Ausführung mit /tasks das tatsächlich verwendete Modell und vergleiche den zurückgegebenen Auszug mit dem ursprünglichen Log. maxTurns begrenzt die Anzahl der Gesprächsrunden, nicht Dollarbeträge oder Tokens. Wird das Limit erreicht, kann das Ergebnis unvollständig bleiben. Die Subagent-Referenz beschreibt diese Felder und die Details zum Laden und Ausführen.

haiku ist ein Alias; welches konkrete Modell dahintersteht, bestimmt die Anbieterkonfiguration. Überlasse schwierige Architekturentscheidungen oder die Fehlersuche bei unklarer Ursache dem Modell, das sie zuverlässig löst. Ein günstiger Subagent, der wiederholt korrigiert werden muss, kann insgesamt mehr kosten.

Wenn du BetterToken für nutzungsabhängig abgerechneten Modellzugriff verwendest, folge dessen Claude-Code-Konfiguration: Die Anthropic-kompatible Basis-URL lautet https://bettertoken.ai, ohne /v1. Prüfe ANTHROPIC_DEFAULT_HAIKU_MODEL und die weiteren Aliaszuordnungen. Wenn alle Aliasse auf dieselbe Modell-ID zeigen, wählt haiku kein anderes, günstigeres Modell aus. Wähle unterstützte IDs gezielt, vergleiche die aktuellen Modell- und Cache-Preise und prüfe das protokollierte Modell sowie die berechneten Kosten. Die API-Abrechnung von BetterToken ist von einem Claude-Abo getrennt. Behandle diese Anbieterkonfiguration als eigenen Aufbau, getrennt vom obigen Headroom-Versuch mit direktem Anthropic-Zugang.

Entscheide nach Gesamtkosten und Korrektheit der erledigten Aufgabe

Behalte ein Komprimierungstool nur dann bei, wenn es die Bilanz der vollständig erledigten Aufgabe verbessert, einschließlich Cache-Effekten, Subagents, nachgeladenen Inhalten und Wiederholungsversuchen.

Vergleiche denselben Repository-Stand, denselben Prompt, dasselbe konkrete Modell, dieselbe Aufwandseinstellung und denselben Prüfungsbefehl. Notiere, ob ein Durchlauf mit bereits gefülltem oder leerem Cache beginnt; unterschiedliche Ausgangsbedingungen können den Vergleich verfälschen. Prüfe sowohl den fertigen Patch beziehungsweise die Antwort als auch die dafür angeführten Belege.

Bei der Anthropic-API-Abrechnung sind input_tokens, cache_creation_input_tokens und cache_read_input_tokens getrennte Kategorien. input_tokens allein bildet also nicht die gesamte Eingabe ab. Beziehe auch Ausgabetokens ein. Berechne bei Preisen pro Million Tokens für alle Anfragen sum(token_count × category_rate / 1,000,000). Trenne Cache-Schreibvorgänge nach Aufbewahrungsdauer, wenn dafür unterschiedliche Preise gelten, und addiere verpflichtende Gebühren, die nicht nach Tokens berechnet werden.

Die Cache-Anzeige für das Hauptgespräch in Claude Code setzt Version 2.1.251 oder neuer voraus und umfasst keine Subagents. Die Einsparungszähler des Proxys helfen bei der Diagnose; verwende für den Kostenvergleich jedoch die Abrechnungsdaten deines Anbieters.

Wenn ein ausgelassener Fehler eine weitere Untersuchung auslöst, ein Subagent wiederholt Unterstützung benötigt oder das Nachladen den ursprünglichen Kontextumfang wiederherstellt, reduziere die Komprimierung oder grenze die Aufgabe anders ein. Das Ziel ist ein korrektes Ergebnis mit insgesamt weniger kostenpflichtiger Arbeit.