Headroom řeší praktický problém AI agentů: do modelu často neposílají jen krátký prompt, ale dlouhé výpisy nástrojů, logy, výsledky hledání v kódu, RAG chunky, soubory a historii konverzace. Projekt tyto vstupy komprimuje ještě před tím, než dorazí k LLM. Cíl není změnit samotný model, ale zmenšit množství kontextu, které musí zpracovat. Pro vývojáře to znamená menší spotřebu tokenů u nástrojů jako Claude Code, Codex, Cursor, Aider nebo Copilot CLI.
Za projektem stojí Tejas Chopra, na GitHubu vystupující jako chopratejas. Headroom je open-source projekt pod licencí Apache 2.0 a hlavní repozitář uvádí přes 35 tisíc hvězd. Autor projekt popisuje jako lokální vrstvu pro kompresi kontextu, která běží mezi aplikací nebo agentem a poskytovatelem LLM.
The context compression layer for AI agents
Použití může být několik. Headroom lze zapojit jako Python nebo TypeScript knihovnu přes compress(messages), jako lokální proxy přes headroom proxy --port 8787, jako wrapper pro konkrétního agenta přes headroom wrap, nebo jako MCP server. Podporuje také integrace pro LiteLLM, LangChain, Agno, Vercel AI SDK a ASGI aplikace. U LiteLLM se například přidá callback, který zprávy zkomprimuje v pre_call_hook ještě před odesláním providerovi.
Technicky Headroom nejdřív rozpozná typ obsahu a podle toho zvolí vhodný způsob zpracování. JSON může projít přes SmartCrusher, zdrojový kód přes AST-aware CodeCompressor a běžný text přes model Kompress-base. Součástí pipeline je také CacheAligner pro stabilnější prefixy a CCR, tedy reverzibilní komprese. Originály zůstávají uložené lokálně a model si je může přes nástroj headroom_retrieve vyžádat, pokud zkomprimovaná verze nestačí.
Projekt uvádí úsporu 60–95 % tokenů podle typu workloadu. Na konkrétních příkladech uvádí například zmenšení code search výstupu ze 17 765 na 1 408 tokenů, SRE incident debugging z 65 694 na 5 118 tokenů a GitHub issue triage z 54 174 na 14 761 tokenů. U benchmarků projekt uvádí zachování skóre u GSM8K na 0,870, zlepšení TruthfulQA z 0,530 na 0,560 a 97% skóre u SQuAD v2 i BFCL při kompresi 19 %, respektive 32 %.
Zajímavé je, že Headroom neřeší jen vstupní prompt. Volitelně umí tvarovat i výstup modelu, například omezit zbytečné úvody, opakování kódu nebo příliš hluboké rozepisování rutinních kroků. Tato část se zapíná zvlášť přes HEADROOM_OUTPUT_SHAPER=1 a projekt u ní uvádí měření odhadované úspory výstupních tokenů s intervalem spolehlivosti. Pro agenty, kteří často čtou dlouhé soubory a logy, je ale hlavní přínos pořád v tom, že komprese probíhá lokálně a před samotným voláním modelu.
Zdroje:
