95% экономии токенов: Headroom на GitHub

Headroom на GitHub — это open-source проект, который за несколько месяцев собрал больше 37 тысяч звёзд и стал одним из самых обсуждаемых инструментов для тех, кто ежедневно гоняет Claude Code, Codex или Cursor и упирается в лимиты токенов.

Если вы работаете с AI-агентами и замечаете, что контекстное окно забивается логами, повторяющимся кодом и JSON-мусором быстрее, чем успеваете дописать задачу — это ровно та проблема, которую решает Headroom.

Разберём, что это за проект, как он устроен внутри, сколько реально экономит и как его поставить — без маркетинговых обещаний, только по документации и исходникам репозитория.

Каждый вызов инструмента, чтение файла, ответ базы данных или результат RAG-поиска, который видит ваш AI-агент — это на 70–95% техническая обвязка: повторяющиеся поля JSON, отступы кода, служебные строки логов. Модель всё это честно читает и оплачивает как токены, хотя полезной информации там — доли процента.

Headroom встаёт между агентом и провайдером (Anthropic, OpenAI, Bedrock, Vertex AI и ещё сотней LLM через LiteLLM) и сжимает этот поток до того, как он долетит до модели.

Автор проекта — разработчик Tejas Chopra, репозиторий живёт под адресом `github.com/chopratejas/headroom`, лицензия Apache 2.0, то есть бесплатно для коммерческого использования.

Работает в трёх режимах: как прозрачный прокси (вообще без изменений кода), как Python/TypeScript-библиотека с функцией `compress()`, либо как готовая интеграция с фреймворками — LangChain, Agno, Strands, MCP.

Для тех, кто хочет встроить сжатие прямо в код, вызов выглядит буквально в две строки:

Никакой магии — на выходе обычный список сообщений, который дальше уходит в клиент Anthropic, OpenAI или любой другой без переделок.

В основе — двухэтапный конвейер, который выполняется на каждый запрос.

**Этап 1: CacheAligner.** Стабилизирует префиксы сообщений так, чтобы у провайдера действительно срабатывал KV-кэш. У Anthropic, например, кэшированные префиксы читаются с 90% скидкой — но только если начало запроса не «плывёт» от раза к разу. CacheAligner следит, чтобы это условие соблюдалось.

**Этап 2: ContentRouter.** Автоматически распознаёт тип контента и направляет его нужному компрессору — вручную ничего настраивать не нужно.

Важный нюанс, который часто упускают в пересказах: ничего не удаляется безвозвратно. Сжатые данные попадают в хранилище CCR (Compress-Cache-Retrieve), а модель получает инструмент `headroom_retrieve`, которым может при необходимости запросить полный оригинал. То есть это не «обрезание» контекста, а обратимое сжатие.

Внутри у всего этого — единый жизненный цикл запроса, одинаковый что для `compress()`, что для SDK, что для прокси:

Практическая польза для разработчика в том, что на каждую из этих стадий можно повесить собственный обработчик через `on_pipeline_event(...)` — например, чтобы логировать экономию в свою систему мониторинга, а не только смотреть дашборд Headroom.

Разработчик публикует бенчмарки на реальных рабочих сценариях, а не на синтетических тестах.

Отдельно стоит отметить кейс со 100 записями продакшн-логов, где один критичный error был «зарыт» на 67-й позиции: базовый запрос занял 10 144 токена, после Headroom — 1 260, то есть 87,6% экономии, и в обоих случаях модель правильно нашла ошибку в 4 из 4 попыток.

Здесь и родилась цифра из заголовка: 95% — это не средний показатель по всем сценариям, а максимум, который достигается на хорошо сжимаемых типах данных вроде JSON.

На «живом» исследовании кода, где почти каждая строка несёт уникальный смысл, экономия куда скромнее — 47%. Это честная деталь, которую стоит держать в голове перед тем, как ставить Headroom и ждать одинаковой экономии везде.

Точность ответов при этом не проседает — разработчик прогоняет проект через стандартные бенчмарки:

Проект требует Python 3.10+, доступен через pip, npm и Docker.

Через pip (Python-библиотека и CLI):

Через npm (TypeScript/Node.js SDK):

Через Docker:

Для тонкой настройки есть отдельные «наборы»: [proxy] — прокси-сервер и MCP-инструменты, [ml] — модель Kompress для текстового сжатия (требует torch), [langchain] и [agno] — интеграции с соответствующими фреймворками.

После установки достаточно одной команды, чтобы поднять прокси и подключить к нему любой инструмент:

Отдельная команда headroom wrap запускает прокси и сразу направляет в него трафик выбранного агента:

Отдельного внимания заслуживает функция headroom learn — она анализирует прошлые сессии агента, находит паттерны неудачных вызовов инструментов и записывает выводы прямо в CLAUDE.md или AGENTS.md, чтобы агент не наступал на те же грабли повторно.

Есть и менее очевидная возможность — Headroom умеет сокращать не только то, что модель читает, но и то, что она пишет в ответ.

На моделях уровня Opus вывод стоит в пять раз дороже ввода, а значительная его часть — это вступительные фразы вроде «сейчас сделаю» и повторный вывод кода, который агент только что показал сам себе.

Флаг HEADROOM_OUTPUT_SHAPER=1 включает укорачивание таких ответов и снижение «усилия на размышление» в рутинных шагах — при этом на новых вопросах и ошибках модель, по заявлению разработчика, работает с полным усилием без изменений.

Отдельно стоит сказать про режим подписки GitHub Copilot: командой headroom copilot-auth login можно завести отдельный OAuth-токен именно для Headroom и пропускать через локальный прокси трафик Copilot CLI — это удобно, если основной GitHub-токен вы не хотите светить лишний раз.

На рынке есть похожие инструменты, но разница в охвате и обратимости заметна сразу:

Прежде чем ставить Headroom, стоит учесть несколько практических моментов.

Python 3.10+ обязателен. На системах со свежее Python 3.14 часть функций (учёт стоимости через LiteLLM) не работает — экономия токенов считается корректно, но денежная оценка показывает $0.00, поскольку LiteLLM пока не устанавливается на 3.14.

Корпоративные сети с SSL-инспекцией. Если при установке падает ошибка CERTIFICATE_VERIFY_FAILED, значит сеть использует MITM-прокси с корпоративным сертификатом. Решение — поставить Rust вручную до установки пакета, чтобы сборочный бэкенд не пытался скачивать rustup по недоверенному соединению.

Когда Headroom не нужен. Если вы работаете только с нативной компакцией одного провайдера и не запускаете нескольких агентов одновременно — выгода будет минимальной. То же самое касается изолированных песочниц, где локальные процессы запускать нельзя: прокси там просто негде поднять.

Требования к железу для ML-функций. ONNX-модуль для распознавания контента и оценки релевантности требует AVX2 на x86. На старых облачных виртуалках или в QEMU без AVX2 Headroom автоматически откатывается на эвристические методы вместо ONNX — без падений, но с чуть менее точным определением типа контента. На arm64 и Apple Silicon это ограничение не действует.

Headroom — это бесплатно?

Да, проект распространяется по лицензии Apache 2.0, использовать можно и в коммерческих продуктах без отчислений автору.

Нужен отдельный API-ключ или аккаунт для работы Headroom?

Нет. Headroom не подменяет собой провайдера — он работает как локальный слой перед вашим существующим клиентом Anthropic, OpenAI или другого сервиса и использует те же ключи, что вы уже настроили.

Безопасно ли пускать весь трафик агента через прокси Headroom?

Прокси поднимается локально, на вашей машине или в вашей инфраструктуре, и данные никуда за пределы этого контура не уходят — это отдельно подчёркивается в документации проекта: «ваши данные остаются здесь». Хранилище CCR с оригиналами сжатых данных тоже локальное.

Работает ли Headroom на Windows?

Прокси и CLI кроссплатформенны, но не все механизмы аутентификации одинаково обкатаны: хранение токенов через macOS Keychain уже проверено в бою, а Windows Credential Manager и Linux Secret Service реализованы, но пока не прошли полноценную валидацию на реальных системах — для Docker и CI разработчик советует передавать токен явной переменной окружения, а не полагаться на системное хранилище.

Чем Headroom лучше встроенной компакции истории диалога у самого провайдера?

Встроенная компакция работает только с историей переписки и требует доверять облаку провайдера. Headroom сжимает вообще весь контекст — логи, файлы, RAG, инструменты — локально и обратимо, плюс работает одинаково для любого провайдера, а не только для одного.

Что если сжатие исказит важные данные и агент ошибётся?

Формально это исключено архитектурой CCR: ничего не удаляется, а только сжимается с возможностью восстановить оригинал через инструмент headroom_retrieve. Если всё же нужна чистая проверка, можно оставить часть трафика без сжатия через HEADROOM_OUTPUT_HOLDOUT и сравнить результат с контрольной группой.

Headroom имеет смысл ставить, если вы каждый день работаете с AI-агентами и хотите сократить расходы без переписывания кода, используете несколько агентов параллельно и хотите, чтобы они делили общую память, или вам важна обратимость — возможность в любой момент восстановить исходные данные из CCR-хранилища.

Для разового использования одного агента в облачной песочнице выгода будет не такой очевидной — там проще обойтись встроенной компакцией провайдера.

Стоит держать в голове и то, что все цифры экономии в статье — это данные из собственных бенчмарков автора проекта, а не независимой лаборатории.

Общая методика прозрачна и воспроизводима командой python -m headroom.evals suite --tier 1, но на своих задачах цифры почти наверняка будут отличаться от табличных: слишком многое зависит от того, насколько «шумный» у вас контекст.

Проект живёт активно — только за последние релизы в changelog видны и правки безопасности, и доработки прокси для разных провайдеров, так что для тех, кто ставит инструмент в долгую, вопрос не «работает ли сейчас», а «насколько быстро чинят баги» — тут у Headroom, судя по частоте релизов, ситуация выглядит здоровой.

Пробовали уже подключать Headroom к своим агентам — и на каких сценариях экономия оказалась заметнее всего?

Источники:

headroom github

Официальные ресурсы и материалы по ИИ

Главный сайт с документацией