Headroom: minder tokens naar je LLM, wat levert het echt op?

Werk je met AI-agents die code schrijven, codebases doorzoeken of storingen debuggen, dan ken je het probleem: de context loopt vol met logs, JSON en tool-output waarvan het model maar een fractie nodig heeft. Je betaalt voor elk van die tokens. Headroom pakt dat aan voordat de tekst bij het model aankomt. Het open-source project staat sinds januari 2026 op PyPI, groeide uit tot zo’n 78.000 GitHub-sterren en zit inmiddels op versie 0.42.0 (26 oktober 2026) (Bron: PyPI).

Update 2 november 2026 Dit stuk is herschreven op basis van de huidige documentatie. Het project verhuisde naar de GitHub-organisatie headroomlabs-ai en valt onder de Apache-2.0-licentie. De Python-functie compress() werkt nu op een lijst berichten. De besparingscijfers zijn genuanceerd: de 60 tot 95% geldt vooral voor JSON. Ook bleek dat er standaard een anonieme gebruiksteller meeloopt.

Wat Headroom doet

Het idee is eenvoudig: eerst comprimeren, dan pas naar het model sturen. Een onderdeel dat Headroom de ContentRouter noemt, kijkt wat voor inhoud er in de context staat en kiest per stuk een techniek (Bron: Headroom op GitHub):

• SmartCrusher voor JSON, zoals lange arrays met bijna gelijke records;
• Kompress-v2-base, een eigen model op Hugging Face, voor tekst en logs;
• CodeCompressor, die de structuur van code begrijpt (AST) en werkt voor onder meer Python, TypeScript, Go, Rust en Java. Daarvoor heb je de extra [code] nodig;
• een compressor voor afbeeldingen die volgens het project 40 tot 90% scheelt.

Wat er niet gebeurt, is minstens zo belangrijk. Volgens de documentatie blijven broncode, grep-zoekresultaten, systeemprompts en RAG-documenten standaard onaangeroerd. Headroom is extra voorzichtig met code: bevat je laatste bericht woorden die op analyse wijzen, dan blijft alle code in het gesprek heel. Korte berichten onder de 50 tokens worden overgeslagen, omdat de rekentijd dan meer kost dan het oplevert (Bron: Headroom Limitations).

Vier manieren om het te gebruiken

Installeren gaat met pip (Python 3.10 of nieuwer). Daarmee krijg je ook de opdracht headroom op de commandline:

pip install "headroom-ai[all]"

1. Als library. Je geeft je berichtenlijst aan compress() en stuurt het resultaat door naar je model. Dit voorbeeld komt uit de README:

from headroom import compress
from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")

client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")

2. Als proxy. Met headroom proxy start je een tussenlaag die standaard luistert op 127.0.0.1:8787 en verkeer voor de Anthropic- en OpenAI-API’s comprimeert en doorstuurt (Bron: Headroom Proxy). Je laat je client dan naar die lokale poort wijzen in plaats van naar de aanbieder.

3. Rond een coding agent. headroom wrap claude start de proxy en laat Claude Code erdoorheen lopen. Hetzelfde werkt volgens de README voor onder meer Codex, Aider, Cline, OpenCode, Goose en OpenClaw. Cursor vraagt een handmatige instelling.

4. Als MCP-server. Met headroom mcp install krijgt je agent drie MCP-tools: headroom_compress, headroom_retrieve en headroom_stats. De agent kan dan zelf beslissen wanneer hij iets comprimeert of een origineel terughaalt.

Gevorderden Compressie gebeurt fail-open. Kapotte JSON gaat ongewijzigd door en ontbreekt een optionele afhankelijkheid, dan schrijft Headroom alleen een waarschuwing in het log. Dat is veilig voor je antwoorden, maar je merkt het niet als er niets gecomprimeerd wordt. Controleer de besparing dus via headroom_stats of de savings-tracking in plaats van aan te nemen dat het werkt.

Omkeerbaar en lokaal, met één kanttekening

Headroom bewaart de originelen in een lokale cache. Het project noemt dat CCR, kort voor Compress-Cache-Retrieve: heeft het model meer detail nodig, dan haalt het het origineel op via headroom_retrieve (Bron: Headroom CCR). Je verliest dus geen data, al moet het model wel zelf doorhebben dat het iets mist.

De compressie draait op je eigen machine en de proxy luistert standaard alleen lokaal. Je verzoeken gaan daarna naar de aanbieder die je instelt, zoals je gewend bent. Eén ding is goed om te weten: er staat standaard een anonieme “beacon” aan die tellers naar Headroom Labs stuurt, zoals tokentotalen, compressieverhoudingen, model-ID’s en je besturingssysteem. Prompts, antwoorden, code en bestandspaden gaan volgens de documentatie niet mee. Wil je dat niet, zet dan HEADROOM_BEACON=off of DO_NOT_TRACK=1 (Bron: Headroom Proxy).

Wat je kunt verwachten

De eerlijkste samenvatting komt van het project zelf: ongeveer 20% minder tokens bij coding agents en 60 tot 95% bij JSON. In de eigen testset scheelde het 21% bij code zoeken, 30% bij het sorteren van GitHub-issues, 42% bij het verkennen van een codebase en 57% bij het debuggen van een storing. Een grote logdump ging van 10.144 naar 1.260 tokens. Op de rekenbenchmark GSM8K bleef de score gelijk op 0,870, met en zonder Headroom (Bron: Headroom op GitHub).

De documentatie zegt er zelf bij dat dit losse metingen op synthetische data zijn, geen herhaalbare benchmark. Meet dus op je eigen verkeer, bijvoorbeeld met de functie simulate() (Bron: Headroom Limitations). Het meeste haal je eruit bij lange sessies met veel tool-output en logs. Bij korte gesprekken of sessies die bijna alleen uit code bestaan, scheelt het weinig.

Hoe snel tokenkosten kunnen oplopen, liet Uber zien: het bedrijf had zijn AI-budget voor heel 2026 in april al op en zette daarna een limiet van 1.500 dollar per medewerker per tool per maand (lees het hele verhaal). Waar de kosten van een taalmodel vandaan komen, lees je in AI-inferentie: van tokens tot watts.