Headroom — стиснення контексту для AI-агентів і чесна статистика токенів

Headroom (github.com/headroomlabs-ai/headroom) — це прошарок, який стискає все, що читає твій AI-агент: виводи інструментів, логи, файли, результати пошуку, історію діалогу. До моделі приходить те саме за змістом, але помітно менше за обсягом. Ліцензія Apache 2.0, працює локально — дані нікуди не їдуть.

Чотири способи підключити

• Проксі. headroom proxy --port 8787 — нуль змін у коді, будь-яка мова.
• Обгортка агента. headroom wrap claude (також codex, cursor, aider, copilot, opencode та інші) — одна команда, відкат через headroom unwrap.
• Бібліотека. compress(messages) у Python або TypeScript просто всередині свого застосунку.
• MCP-сервер. Три інструменти — headroom_compress, headroom_retrieve, headroom_stats — для будь-якого MCP-клієнта.

Найцікавіше — статистика

Більшість інструментів навколо LLM обіцяють економію, але не дають подивитися на власні витрати. Тут навпаки: headroom savings, headroom stats і headroom dashboard показують по днях, по моделях і по клієнтах, скільки токенів пішло і в які гроші це стало. Одразу видно, який проєкт скільки з'їдає.

Ось реальний зріз моєї робочої сесії з Claude Code, без прикрас: 118 запитів до API, з них 74 стиснуто, прибрано 37 249 токенів; сесія коштувала б $3,65 — вийшло $3,50. Плюс майже 4 мільйони токенів прочитано з кешу провайдера. Розбивка по моделях окремим рядком: opus — свої гроші, haiku — свої.

Цифри, які варто читати уважно

У README заявлено 60–95% економії на JSON-даних і 15–20% на кодових агентах. Обидві цифри чесні, але це різні сценарії. На моїй сесії середнє стиснення було близько 1–4% — і це нормально: більшість запитів кодового агента «приморожені» префіксом, який уже лежить у кеші провайдера. Headroom навмисно їх не чіпає, бо переписати такий префікс — значить зламати кеш і заплатити більше, ніж зекономив.

Великі відсотки живуть там, де багато свіжого «сміття»: пошук по коду (17 765 → 1 408 токенів), розбір інциденту, тріаж issue. У бенчмарках при цьому точність не просідає: GSM8K — без змін, TruthfulQA — навіть трохи вище базового.

Інструмент, який замість красивого відсотка показує «ось стільки, і ось чому саме стільки» — це рідкість. Довіри до нього більше.

Стиснення, яке можна відкотити

Всередині — маршрутизатор типів контенту: JSON іде в SmartCrusher, код — у компресор, що розуміє AST (Python, JS/TS, Go, Rust, Java, C/C++), звичайний текст — у власну модель Kompress-v2-base. Найважливіше — оборотність: оригінали лежать локально, і якщо моделі раптом знадобляться подробиці, вона просто викликає headroom_retrieve.

Як це виглядає на практиці: у моєму терміналі великий файл згорнувся в рядок-маркер із хешем, а коли знадобився повний текст — один виклик і оригінал на місці. Нічого не втрачено, просто до моделі воно доїхало вдесятеро легшим.

Дрібниці, які приємно здивували

• Економія на виході. HEADROOM_OUTPUT_SHAPER=1 підрізає те, що модель пише у відповідь — преамбули, переписаний код, зайві «роздуми» на рутинних кроках. А в звіті — оцінка з довірчим інтервалом, а не вигадане число.
• headroom learn. Розбирає невдалі сесії й дописує висновки в CLAUDE.local.md, щоб агент не наступав на ті самі граблі.
• Спільна пам'ять між агентами. Claude, Codex, Gemini і Grok працюють з одним сховищем.

Кому варто спробувати

Якщо ти щодня ганяєш кодових агентів або будуєш власного — варто хоча б заміряти. Старт займає хвилину:

• pip install "headroom-ai[all]" (потрібен Python 3.10+, для доларової статистики краще 3.13)
• headroom wrap claude — і працюй як завжди
• headroom savings — подивитися, у що це вилилося

Якщо ж ти сидиш на одному провайдері й тобі вистачає його вбудованої компакції — можна спокійно пройти повз. А от коли агенти крутяться в CI або в команді кілька людей палять токени щодня — рахунок стає видимим, і це вже привід.

Маєш ідею, де AI-агенти зекономили б вам час і гроші? Напишіть мені — розберемося разом.