Headroom: Tool-Ausgaben, Logs und Dateien eines Agenten lokal komprimieren, bevor sie das LLM erreichen, mit Abruf des Originals bei Bedarf

headroomlabs-ai/headroom ist ein quelloffenes Python-Projekt unter der Apache-2.0-Lizenz. Es wurde am 7. Januar 2026 angelegt, der letzte Push war am 13. Oktober, und es hat beim Schreiben etwa 75.257 Sterne und 5.838 Forks. Das Versprechen ist ein Satz: alles komprimieren, was ein KI-Agent liest, also Tool-Ausgaben, Logs, RAG-Schnipsel, Dateien und Gesprächsverlauf, bevor es das LLM erreicht, sodass die Antworten gleich bleiben und nur ein Bruchteil der Token übrig ist. Das README betont, die Kompression laufe auf Ihrem Rechner, und kein Prompt- oder Dateiinhalt werde zum Komprimieren irgendwohin gesendet. Es zielt auf eine verbreitete Verschwendung: Eine Suche liefert hundert Ergebnisse, ein Log wiederholt tausendmal dieselbe Zeile, und alles gelangt in den Kontext, belegt das Fenster und wird pro Token abgerechnet.

Die Architektur hat drei Teile. Ein ContentRouter erkennt den Inhaltstyp und wählt einen Kompressor: SmartCrusher für JSON, CodeCompressor für Quellcode über den Syntaxbaum und Kompress-v2-base für normalen Text. CacheAligner markiert nur flüchtige Inhalte, die das KV-Cache-Präfix eines Anbieters brechen würden, und schreibt laut README nie Prompts um. Der Kern ist CCR, die umkehrbare Kompression: Originale werden lokal zwischengespeichert, und das Modell kann headroom_retrieve aufrufen, wenn es den vollen Text braucht. Das beantwortet die übliche Sorge, Information zu verlieren. Die Einbindung ist flexibel: compress(messages) im Code aufrufen, headroom proxy als Proxy ohne Änderung der Anwendung starten, mit headroom wrap eine lange Liste von Programmier-Agenten wie Claude Code, Codex, Cursor und Aider umhüllen oder drei Werkzeuge als MCP-Server anbieten.

Das Projekt bringt mehrere verwandte Funktionen mit. Eine ist ein gemeinsamer Speicher über Agenten hinweg, ein Speicher, den Claude, Codex, Gemini und Grok nutzen, mit automatischer Deduplizierung. Eine andere ist headroom learn, das fehlgeschlagene Sitzungen auswertet und Korrekturen in CLAUDE.local.md (Standard, nicht im Git), CLAUDE.md, AGENTS.md, GEMINI.md oder GROK.md schreibt. Eine dritte ist die Verringerung der Ausgabe-Token. Neben dem Verkleinern dessen, was Sie senden, kürzt der Proxy auch, was das Modell zurückschreibt, mit zwei Methoden. Die „Ausführlichkeitssteuerung“ hängt ans Ende des Systemprompts einen kurzen Hinweis „sei knapp, wiederhole den Kontext nicht“, damit der Prompt-Cache weiter trifft. Das „Aufwandsrouting“ senkt den Denkaufwand, wenn ein Zug nur das Modell ist, das nach einem Tool-Ergebnis wie einem Dateilesen weiterarbeitet, und behält den vollen Aufwand für neue Fragen und Fehler. Das README merkt an, dass bei Modellen der Opus-Klasse die Ausgabe das Fünffache der Eingabe kostet, daher zählt dieser Teil.

Bei den Zahlen nutzt der Benchmark im README vier Szenarien mit festem Seed aus echten Ausgabeformaten von MCP-Servern. Code-Suche (100 Ergebnisse) sinkt von 17.199 auf 13.597 Token, 21 Prozent gespart. Fehlersuche bei einem SRE-Vorfall sinkt von 55.957 auf 24.340, 57 Prozent. Codebasis-Erkundung sinkt von 58.801 auf 33.895, 42 Prozent. GitHub-Issue-Triage sinkt von 46.067 auf 32.429, 30 Prozent. Das Projekt sagt, die Ersparnis hänge davon ab, wie repetitiv die Nutzlast ist: Wiederholte JSON-Arrays und Logzeilen erreichen im Latenz-Benchmark über 90 Prozent, Prosa und ohnehin dichte Ausgaben lassen sich kaum komprimieren. Die Kompression ist schnell: 0,21 ms im Median bei einem 10K-Token-JSON-Suchergebnis und 1,4 ms bei 100K Token. Bei der Genauigkeit mit N=100 liegt GSM8K für Basis und Headroom bei 0,870, und TruthfulQA geht von 0,530 auf 0,560, was laut Projekt im Konfidenzintervall liegt; lesen Sie es als keinen erkennbaren Unterschied. SQuAD v2 erreicht 97 Prozent bei 19 Prozent Kompression, BFCL 97 Prozent bei 32 Prozent.

Wie nutzt man es sicher? Erstens sind alle Zahlen selbst berichtete Benchmarks auf kleinen Stichproben. Führen Sie vor dem Einsatz headroom savings auf Ihrem echten Verkehr aus und erwarten Sie keine großen Gewinne bei bereits kompakten Ausgaben. Zweitens ist headroom wrap nicht nur eine dünne Hülle. Es startet einen lokalen Proxy und installiert Serena für semantische Code-Navigation im umhüllten Projekt, was bei Claude Code bedeutet, einen MCP-Server mit lokalem Geltungsbereich in ~/.claude.json einzutragen. Mit headroom unwrap machen Sie das rückgängig, oder Sie überspringen es per Option. Drittens liegen die Originale zwar lokal im Cache, doch das Modell sieht den komprimierten Text; bedenken Sie das beim Debuggen des Agentenverhaltens. Insgesamt ist es ein klares, umkehrbares und leicht auszuprobierendes Kostenwerkzeug, das man zuerst in einer Testumgebung bewerten sollte.