Headroom – komprese kontextu pro AI agenty

Vytvořeno: 31.7.2026 | Aktualizováno: 31.07.2026 07:18

Headroom je lokální vrstva, která před odesláním požadavku k jazykovému modelu zmenšuje kontext AI agenta. Hodí se hlavně pro agenty jako OpenCode nebo Claude Code, když pracují s dlouhými logy, velkými JSON odpověďmi, mnoha soubory nebo dlouhou historií relace.

AI agent při práci často spouští příkazy a volá nástroje. Jejich výsledek pak musí poslat modelu, aby model rozhodl o dalším kroku. Dlouhý výpis testů nebo tisíce položek z API mohou zbytečně zaplnit kontextové okno a zvýšit počet placených vstupních tokenů.

Headroom není další agent ani náhrada za OpenCode. Je to filtr mezi agentem a API poskytovatele modelu.

OpenCode -> Headroom na localhost -> API modelu

Příklad s OpenCode:

1. Zadání požádá OpenCode o opravu padajících integračních testů.
2. Model navrhne spuštění npm run test:integration a OpenCode tento příkaz provede lokálně.
3. Příkaz vytvoří například tisíce řádků testovacího výpisu. V této chvíli jde jen o data v lokálním procesu; model je ještě nečetl a nevznikly vstupní tokeny u poskytovatele modelu.
4. OpenCode chce výsledek nástroje vložit do dalšího požadavku na model.
5. Pokud je OpenCode spuštěný přes Headroom, lokální proxy požadavek zachytí před odesláním. Z dlouhého výstupu ponechá důležité informace, například chyby, odchylky a relevantní část stack trace, a zkrácenou verzi předá modelu.

OpenCode spustí příkaz
  -> plný lokální log
  -> Headroom log zpracuje a uloží originál lokálně
  -> zkrácený tool output
  -> API modelu

Model tedy nemá v kontextu plný i zkrácený log zároveň. Plný výstup zůstává lokálně, model dostává pouze zkrácenou podobu. Architektura Headroomu popisuje tento postup jako kompresi, lokální cache originálu a jeho případné vyžádání zpět.

Headroom za OpenCode nespouští fetch, shellové příkazy ani MCP nástroje. Tyto akce dál provádí OpenCode. Headroom zasahuje až do okamžiku, kdy OpenCode skládá další API požadavek s výsledkem nástroje.

Headroom také nenahrazuje API modelu. Claude, OpenAI nebo jiný poskytovatel stále vytváří odpověď agenta a je pro něj potřeba běžné ověření či API klíč. Headroom požadavek lokálně upraví a pošle jej dál.

Největší přínos je u opakovaných velkých výstupů:

• Testy, buildy a logy: místo tisíců řádků úspěšných operací může model dostat počet úspěchů, selhání a související chyby.
• JSON z API nebo MCP: opakující se metadata lze zmenšit, ale výjimky a anomálie mají zůstat k dispozici.
• Dlouhé agentní relace: každý další výstup nástroje nepřidává do kontextu stejný objem balastu.
• Více agentů: projekt nabízí i sdílenou lokální paměť pro kontext mezi podporovanými agenty.

Přínosem není samotné zkrácení textu, ale to, že k němu dojde před prvním odesláním velkého výstupu vzdálenému modelu. Lokální zpracování má vlastní nárok na CPU a paměť, ale nemá cenu tisíců vstupních tokenů u API modelu.

Headroom ukládá originál komprimovaného obsahu do lokální cache. Když stručný výstup nestačí, model může přes nástroj Headroomu vyžádat konkrétní původní data. Komprese proto nemusí znamenat trvalou ztrátu detailu.

Například zkrácený testovací výstup může ukázat chybu v src/api/payment.ts na řádku 87. Model pak může požádat o původní část logu kolem daného selhání, místo aby znovu dostal celý výpis testů.

Projekt uvádí přímé zabalení OpenCode příkazem:

headroom wrap opencode

Tím se OpenCode spouští s lokální proxy Headroomu. Konkrétní instalace, podporované volby a případná konfigurace se mají řídit aktuální dokumentací projektu.

Headroom dává smysl, pokud se při práci s agentem opakují velké výstupy nástrojů, relace jsou dlouhé nebo je potřeba šetřit kontextové okno a API tokeny. Projekt uvádí podporu OpenCode i dalších agentů, takže stejné chování lze použít napříč různými klienty.

U malých úloh a krátkých výstupů je přínos malý. Pokud navíc OpenCode už konkrétní výstup kvalitně omezí nebo strukturuje, Headroom může být zčásti redundantní. Komprese také není bez rizika: může vynechat detail, který se později ukáže jako důležitý. Proto je podstatné, že originál zůstává dostupný k vyžádání.

• Headroom – zdrojový kód a dokumentace projektu
• Headroom – architektura