Headroom: Wie das Netflix-Tool die Token-Kosten deiner KI-Agenten um bis zu 95 Prozent senkt

TL;DR: Headroom ist eine Open-Source-Kompressionsschicht von Netflix-Engineer Tejas Chopra, die alles komprimiert, was deine KI-Agenten lesen – Tool-Outputs, Logs, Datei-Inhalte, RAG-Ergebnisse – bevor es das LLM erreicht. Auf realen Agenten-Workloads spart das laut Projekt 60 bis 95 Prozent der Token bei gleicher Antwort. Das Tool läuft lokal, keine Daten verlassen die Maschine, und die Kompression ist reversibel: Das Modell holt sich Originaldaten bei Bedarf per Tool-Call zurück. Eingebunden wird Headroom in einem Befehl (headroom wrap claude), als Proxy, als Library oder als MCP-Server. Lizenz: Apache 2.0.

Was ist Headroom?

Headroom ist die Kontext-Optimierungsschicht (Context Optimization Layer) für LLM-Anwendungen. Sie sitzt zwischen deiner Anwendung oder deinem Coding-Agenten und dem LLM-Provider und schrumpft den Kontext, bevor er das Modell erreicht. Das Versprechen des Projekts: gleiche Antworten, ein Bruchteil der Token. Der Kerngedanke ist simpel. In agentischen Workflows besteht der Kontext zu einem großen Teil aus wiederholten Tool-Outputs, verbosen JSON-Arrays und Boilerplate, die Token kosten, ohne entsprechenden Mehrwert zu liefern. Headroom erkennt den Typ dieser Inhalte und komprimiert jeden mit dem passenden Verfahren.

Wer dahinter steckt

Hinter Headroom steht Tejas Chopra, Senior Engineer bei Netflix, wo er die Datenspeicher für die Empfehlungs-Modelle baut. Headroom ist sein Feierabendprojekt: Als Claude-Code-Vielnutzer stieß er täglich an sein Token-Limit und wollte wissen, wohin die Token eigentlich fließen. Laut seinem Vortrag auf dem Linux-Foundation-Open-Source-Summit (Juni 2026) ist das Projekt rund vier Monate alt, hat etwa 1.900 GitHub-Stars und über 30 Contributor. Die Basis ist Python, dazu gibt es ein TypeScript-SDK und eine Rust-Implementierung in Arbeit.

Was Headroom komprimiert

Headroom beschränkt sich nicht auf einen Inhaltstyp. Komprimiert wird alles, was ein Agent liest: • Tool-Outputs und JSON-Arrays aus API- und Datenbank-Aufrufen • Build- und Test-Logs sowie andere Log-Dateien • Quellcode aus Datei-Reads, Grep und Glob • RAG-Retrievals und Suchergebnisse • Bilder und sogar Video-Frames • Konversationshistorie

Warum verbrennen KI-Agenten so viele Token?

Die meiste Literatur zur Token-Kompression dreht sich um Prompt-Kompression: Sie verdichtet einen blumig formulierten Nutzer-Prompt in etwas semantisch Ähnliches. Chopras Beobachtung ist, dass das am eigentlichen Problem vorbeigeht. In einem Coding-Workflow macht der Nutzer-Prompt nur einen Bruchteil aus. Den Löwenanteil fressen Datei-Reads, externe Tool-Calls, gelesene Webseiten und PDFs. Sein Auslöser war konkret: Eine Claude-Code-Session sollte aus Log-Dateien herausfinden, warum die CPU-Last hochging und der Laptop abstürzte. Das Tool zog die komplette Log-Datei in den Kontext, obwohl 90 Prozent davon irrelevantes Rauschen waren. Dasselbe Muster bei Datenbank-Abfragen: Du bekommst JSON mit vielen Einträgen zurück, brauchst aber nur die 20 Prozent, die die Frage beantworten.

Jede Anfrage schickt die ganze Historie mit

Dazu kommt eine Eigenheit, die viele übersehen. Wenn du mit einem Coding-Agenten sprichst, schickst du nicht jeweils einen neuen Satz an das Modell, sondern jedes Mal die gesamte bisherige Konversation als angehängtes Array. Schon ein simples „Hi“ bedeutet: alles, was bisher gesagt wurde, plus dieses „Hi“ geht erneut an das LLM. Der größte Teil davon wurde längst gesendet. Dagegen bieten die Provider Prefix-Caching an. Anthropic, OpenAI und Google berechnen für bereits gesendete und gecachte Daten nur einen Bruchteil des Preises. Anthropic gibt mit dem passenden cachecontrol-Tag bis zu 90 Prozent Rabatt auf gecachte Reads, OpenAI rund 50 Prozent, Google je nach Modell 75 bis 90 Prozent.

Der Cache-Miss, den du nicht siehst

Der Haken: Ändert sich auch nur eine Kleinigkeit im gecachten Fenster, ist es kein Cache-Hit mehr, und du zahlst für das ganze Fenster den vollen Preis. Genau das passiert ständig unbemerkt. Enthält der System-Prompt ein Datumsfeld oder eine pro Session wechselnde UUID, bekommst du faktisch bei jeder Anfrage einen Cache-Miss. Bei Claude kommt eine weitere Falle dazu: Der Prefix-Cache hat standardmäßig eine Lebensdauer (Time-to-Live, TTL) von fünf Minuten. Bleibst du im Fünf-Minuten-Fenster, bekommst du den günstigen Tarif, danach wird das gesamte Token-Array neu berechnet. Startet Claude für eine Aufgabe einen Sub-Agenten, kann allein dessen Laufzeit das Fenster sprengen. Es gibt zwar eine versteckte Ein-Stunden-TTL, die kostet aber den doppelten Preis bei den Writes, um den Read-Rabatt zu sichern.

Wie funktioniert Headroom?

Headroom ist eine lokale Kompressionsschicht zwischen Agent und Modell. Kein Datenverkehr verlässt deinen Rechner. Intern durchläuft jede Anfrage mehrere Stufen: zuerst der CacheAligner, dann der ContentRouter mit den eigentlichen Kompressoren und schließlich CCR für die Reversibilität.

CacheAligner: Caches wirklich treffen

Der CacheAligner adressiert genau das Cache-Miss-Problem von oben. Er durchsucht System-Prompt und Tool-Definitionen nach dynamischen Feldern wie Datum oder UUID, zieht sie heraus und verschiebt sie ans Ende. So bleibt der vordere, große Teil des Fensters stabil und kassiert weiter den Cache-Rabatt. Die cachecontrol-Tags für Anthropic setzt Headroom automatisch.

ContentRouter und die sechs Kompressoren

Ein universeller Kompressor funktioniert nicht, das war Chopras erste, gescheiterte Idee. Code, JSON und Prosa brauchen unterschiedliche Verfahren. Der ContentRouter erkennt deshalb den Inhaltstyp und wählt den passenden Kompressor, ohne dass du etwas konfigurierst. | Inhaltstyp | Kompressor | Was passiert | Typische Ersparnis | |---|---|---|---| | JSON-Arrays (Tool-Outputs) | SmartCrusher | Statistische Analyse, behält Fehler, Ausreißer und Grenzwerte | 70–90 % | | Quellcode | CodeCompressor | AST-bewusst: behält Signaturen, klappt Funktionskörper ein | 40–70 % | | Logs | (Log-Kompression) | Behält Fehler und Failures, verwirft bestandene Tests | 80–95 % | | Plain Text | Kompress-base | Encoder-Modell bewertet jedes Token auf Behalten oder Verwerfen | 30–50 % | | Git-Diffs | (Diff-Kompression) | Behält geänderte Hunks, verwirft unveränderten Kontext | 40–60 % | | Bilder | (Image-Router) | ML-Router wählt Größe und Qualität pro Bild | 40–90 % | Der SmartCrusher für JSON arbeitet rein statistisch: Er ermittelt Mittelwert und Standardabweichung über die Felder, erkennt, welche Felder für die Anfrage relevant sind, und drückt die unwichtigen zusammen. Im besten Fall meldet das Projekt dafür 83 bis 95 Prozent Ersparnis. Für Prosa nutzt Headroom ein eigenes Modell namens Kompress-base, das auf Hugging Face verfügbar ist. Es ist ein Encoder-Modell, kein Summarizer: Es generiert keinen Text, sondern gewichtet jedes einzelne Token danach, ob seine An- oder Abwesenheit das Ergebnis verändert. Trainiert wurde es auf agentischen Traces. Chopra ist hier selbstkritisch: Das Modell sei „noch nicht das beste“, eine Version 2 ist in Arbeit.

CCR: Kompression mit Rückfahrkarte

Die wichtigste Idee ist CCR (Compress-Cache-Retrieve). Headroom komprimiert aggressiv, behält die Originale aber lokal (gestützt auf Redis und SQLite) und hinterlässt im komprimierten Text eine ID. Dem Modell wird per Tool-Call-Beschreibung mitgeteilt: Fehlt dir Information, ruf das Tool headroomretrieve mit dieser ID auf. So ist die Kompression reversibel, nichts wird wirklich weggeworfen. In der Praxis ruft das Modell die Originale laut Chopra in rund 99 Prozent der Fälle gar nicht ab, weil es seine Antwort auch ohne sie findet. Hinweis: Der CCR-Speicher ist standardmäßig flüchtig (Fünf-Minuten-TTL). Brauchst du ältere Originale, musst du die TTL hochsetzen, was Speicher kostet.

Wie installierst und nutzt du Headroom?

Installiert wird Headroom je nach Ökosystem über pip, npm oder Docker: Vorausgesetzt wird Python 3.10 oder neuer. Über granulare Extras wie [proxy], [mcp], [ml], [code] oder [memory] kannst du nur die Teile installieren, die du brauchst. Für die Einbindung gibt es vier Wege.

Modus 1: Agent wrappen (kein Code-Change)

Der einfachste Einstieg. Ein Befehl startet den lokalen Proxy und leitet alle Calls deines Agenten hindurch: Statt claude funktioniert auch codex, cursor, aider oder copilot. Du musst nichts an deinem Code ändern.

Modus 2: Drop-in-Proxy

Du startest Headroom als lokalen Proxy und zeigst mit deinen bestehenden OpenAI- oder Anthropic-SDK-Calls auf localhost statt auf die Provider-URL: Das funktioniert sprach- und framework-unabhängig, die einzige Änderung ist die Base-URL.

Modus 3: Inline-Library

Für feinere Kontrolle rufst du die Kompression direkt im Code auf: In TypeScript geht das analog mit await compress(messages, { model }). Außerdem gibt es fertige Integrationen für LangChain, Agno, Strands, LiteLLM und das Vercel AI SDK sowie Wrapper für die Anthropic- und OpenAI-Clients.

Modus 4: MCP-Server

Für MCP-Clients wie Claude Code oder Cursor installierst du Headroom als Model-Context-Protocol-Server: Das stellt drei Tools bereit: headroomcompress, headroomretrieve und headroomstats. Wie du MCP-Server generell an Claude Code anbindest, zeigt der Guide zur DataForSEO-MCP-Anbindung.

Mehr als Kompression: Memory und Lernen

Headroom bringt zwei Features mit, die über reine Kompression hinausgehen. Mit Cross-Agent-Memory teilen Claude, Codex und Gemini einen gemeinsamen, deduplizierten Kontext-Speicher (lokal über SQLite). Und headroom learn durchforstet fehlgeschlagene Sessions, korreliert sie mit erfolgreichen und schreibt die Erkenntnisse als Korrekturen in deine CLAUDE.md, AGENTS.md oder GEMINI.md. Den aktuellen Stand prüfst du jederzeit mit headroom stats.

Was bringt Headroom konkret?

Die Projekt-Benchmarks auf realen Agenten-Workloads zeigen, wie stark die Ersparnis vom Inhaltstyp abhängt: | Workload | Vorher | Nachher | Ersparnis | |---|---|---|---| | Code-Suche (100 Ergebnisse) | 17.765 | 1.408 | 92 % | | SRE-Incident-Debugging | 65.694 | 5.118 | 92 % | | GitHub-Issue-Triage | 54.174 | 14.761 | 73 % | | Codebase-Exploration | 78.502 | 41.254 | 47 % | Ein anschauliches Beispiel: 100 Log-Einträge mit einem einzigen kritischen Fehler an Position 67 schrumpfen von 10.144 auf 1.260 Token, eine Reduktion von 87,6 Prozent. Die Antwort bleibt identisch, der FATAL-Fehler wird automatisch erhalten, nicht durch Keyword-Matching, sondern durch statistische Analyse der Feld-Varianz. Entscheidend ist, dass die Genauigkeit nicht leidet. Auf Standard-Benchmarks bleiben die Werte mit Headroom stabil oder steigen leicht: | Benchmark | Kategorie | Baseline | Headroom | Delta | |---|---|---|---|---| | GSM8K | Mathe | 0,870 | 0,870 | ±0,000 | | TruthfulQA | Faktisch | 0,530 | 0,560 | +0,030 | | SQuAD v2 | QA | – | 97 % | bei 19 % Kompression | | BFCL | Tool-Use | – | 97 % | bei 32 % Kompression | Laut Chopras Vortrag haben die Nutzer bis Juni 2026 zusammen rund 200 Milliarden Token gespart, was er mit etwa 700.000 US-Dollar beziffert. Diese Zahl stammt aus opt-in-Telemetrie, die ausschließlich gesparte Token misst, und ist nach seiner Aussage ein Minimum. Faustregel: Typische Nutzer berichten von 20 bis 30 Prozent Ersparnis, abhängig davon, wie viele Tool-Calls ihr Workflow auslöst. Neben Kosten spart Headroom zwei weitere Dinge: Latenz (ein Nutzer setzt es in einem Voice-Agenten ein, wo es um die Wahrnehmungsschwelle von 200 Millisekunden geht) und Genauigkeit, weil die Modell-Präzision mit wachsendem Kontextfenster nachweislich sinkt. Weniger Rauschen im Fenster hilft dem Modell, sich auf das Signal zu konzentrieren.

Headroom vs. native Compaction und andere Tools

Headroom ist nicht das einzige Tool gegen Kontext-Bloat, hebt sich aber in vier Punkten ab: Es läuft lokal, deckt jeden Inhaltstyp ab, integriert sich mit allen großen Frameworks und ist reversibel. | Tool | Abdeckung | Einsatz | Lokal | Reversibel | |---|---|---|---|---| | Headroom | Alles: Tools, RAG, Logs, Dateien, Historie | Proxy, Library, Middleware, MCP | Ja | Ja | | RTK | CLI-Command-Outputs | CLI-Wrapper | Ja | Nein | | lean-ctx | CLI-Commands, MCP-Tools, Editor-Rules | CLI-Wrapper, MCP | Ja | Nein | | Compresr, Token Co. | Text, der an deren API geht | Hosted-API-Call | Nein | Nein | | OpenAI-Compaction | Nur Konversationshistorie | Provider-nativ | Nein | Nein | Zwei Punkte sind wichtig. Erstens ist die provider-native Compaction stark verlustbehaftet: Sie fasst das Fenster in einer flachen Markdown-Datei zusammen, was viel Information verliert. Zweitens konkurriert Headroom nicht mit RTK, sondern nutzt es: Das RTK-Binary für die Komprimierung von Shell-Outputs ist Teil des Stacks, Headroom komprimiert alles, was danach kommt. Ein interessanter Gegenpol ist der Caveman Mode: Er kürzt die Ausgabe des Modells durch telegrafische Sprache, während Headroom die Eingabe kürzt, bevor sie das Modell erreicht. Beide lassen sich kombinieren, wenn dir maximale Token-Ersparnis wichtig ist.

Wann lohnt sich Headroom – und wann nicht?

Headroom spielt seine Stärke aus, wenn du viel Daten verarbeitest, aber nur einen kleinen Teil davon brauchst. Genau dann ist die Ersparnis am größten. Ein guter Fit ist Headroom, wenn du: • täglich KI-Coding-Agenten nutzt und ohne Code-Änderung sparen willst • über mehrere Agenten hinweg arbeitest und einen geteilten Speicher brauchst • reversible Kompression brauchst, weil Originale per CCR abrufbar bleiben Überspringen oder vorsichtig herangehen solltest du, wenn du: • nur die native Kontext-Verwaltung eines einzelnen Providers nutzt und nicht mehr brauchst • in einer Sandbox arbeitest, in der keine lokalen Prozesse laufen dürfen • ein einfaches Single-Turn-Setup hast, bei dem Kontext-Bloat noch kein echtes Problem ist Die größte Einschränkung ist systembedingt: Wenn das Modell zu aggressiv komprimierte Daten doch braucht und sie per headroomretrieve nachfordert, entsteht ein zweiter Round-Trip. In solchen Fällen kannst du mit Headroom in Summe sogar mehr Token verbrauchen als ohne. Genau hier soll headroom learn gegensteuern, indem es lernt, beim nächsten Mal weniger stark zu komprimieren. Auch der Effekt schwankt: In einem unabhängigen Test brachte Headroom bei niedrigem Reasoning-Aufwand auf Opus gar keine Ersparnis, sichtbar wurde sie erst ab mittlerem Aufwand und vielen Tool-Calls. Und in Unternehmen, die Claude bereits über einen eigenen Proxy (etwa LiteLLM) laufen lassen, ist die saubere Integration laut Chopra noch in Arbeit. Beim Datenschutz gibt Headroom Entwarnung: Es läuft lokal, sensible Felder wie PII oder PHI werden nicht komprimiert, und die opt-in-Telemetrie erfasst nur die Zahl der gesparten Token.

FAQ: Häufig gestellte Fragen zu Headroom

Ist Headroom kostenlos? Ja. Headroom ist Open Source unter der Apache-2.0-Lizenz und vollständig lokal lauffähig. Es gibt keine Pflicht zu einem kostenpflichtigen Cloud-Dienst, die Telemetrie ist opt-in und erfasst nur gesparte Token. Verliere ich durch die Kompression Informationen? Nein, zumindest nicht endgültig. Headroom arbeitet mit CCR (Compress-Cache-Retrieve): Es behält die Originale lokal und gibt dem Modell ein Tool, um sie bei Bedarf zurückzuholen. Die Kompression ist also reversibel, auch wenn ein solcher Abruf einen zusätzlichen Round-Trip kostet. Funktioniert Headroom mit Claude Code? Ja. Der schnellste Weg ist headroom wrap claude, das den lokalen Proxy startet und alle Calls hindurchleitet. Alternativ bindest du Headroom als MCP-Server ein oder lässt Claude Code über die Proxy-Base-URL laufen. Auch Codex, Cursor, Aider und Copilot CLI werden unterstützt. Geht durch Headroom die Genauigkeit verloren? Nach den Projekt-Benchmarks nicht. Auf GSM8K, TruthfulQA, SQuAD v2 und BFCL bleiben die Werte mit Kompression stabil oder verbessern sich leicht. Die Begründung: Weniger Rauschen hilft dem Modell, sich auf das Signal zu konzentrieren. Die Genauigkeits-Messung ist laut Projekt aber noch in Entwicklung. Welche Daten verlassen meinen Rechner? Standardmäßig keine. Headroom ist als lokale Schicht konzipiert, die Kompression und der CCR-Speicher laufen auf deiner Maschine. Nur wenn du die Telemetrie aktiv erlaubst, wird die Zahl der gesparten Token geteilt, keine Inhalte. Worin unterscheidet sich Headroom von Prompt-Kompression? Prompt-Kompression verdichtet den Nutzer-Prompt. Headroom setzt am eigentlichen Token-Fresser an: an Tool-Outputs, Datei-Reads, Logs und RAG-Ergebnissen, die in agentischen Workflows den größten Teil des Kontexts ausmachen.

Fazit

Headroom adressiert ein reales Problem, das jeder Vielnutzer von Coding-Agenten kennt: Der Kontext füllt sich mit Rauschen, und du zahlst dafür. Der lokale, reversible Ansatz mit content-spezifischen Kompressoren ist durchdacht, und die Einbindung über headroom wrap ist in 60 Sekunden erledigt. Realistisch sind eher 20 bis 30 Prozent Ersparnis im Alltag als die plakativen 95 Prozent, und der mögliche zweite Round-Trip ist eine echte Einschränkung. Für tägliche Claude-Code- oder Codex-Nutzer ist ein Test trotzdem die Zeit wert. Wo Tools wie Headroom über Hooks andocken, erklärt der Überblick zu KI-Agenten – und wer Kosten anders senken will, findet im Guide zu DataForSEO-MCP und im Beitrag zu Hermes ergänzende Ansätze. Verifizierte Quellen: GitHub-Repository chopratejas/headroom, Headroom-Dokumentation, Hugging-Face-Modell chopratejas/kompress-v2-base, Vortrag von Tejas Chopra auf dem Linux-Foundation-Open-Source-Summit (YouTube, Juni 2026).