Как перестать скармливать LLM лишние токены и начать экономить на API

Представьте, что вы используете Claude Code или Cursor для отладки сложного бага. Агент лезет в логи, читает JSON-ответы от API, просматривает десятки файлов. В какой-то момент контекстное окно забивается «мусором»: избыточными полями в объектах, длинными путями в логах или просто повторяющимся кодом. Вы платите за каждый этот токен, а модель начинает путаться в деталях.

Проект Headroom решает эту проблему радикально. Это промежуточный слой между вашим AI-агентом и языковой моделью, который сжимает контекст на 60–95%. Самое приятное, что для модели результат выглядит практически так же, а ответы остаются точными.

Что за зверь такой Headroom

По сути, это локальный прокси-сервер или библиотека, которая перехватывает сообщения перед отправкой в LLM. Она анализирует содержимое — будь то вывод терминала, результаты RAG или куски кода — и применяет к ним специализированные алгоритмы сжатия.

Разработчики проекта заявляют, что при поиске по коду из 100 результатов можно выкинуть 92% токенов без потери смысла. Звучит как магия, но за этим стоит довольно прагматичная инженерная надстройка.

Четыре способа заставить это работать

Разработчики не стали ограничивать нас одним вариантом интеграции. Выбирайте тот, который меньше всего ломает ваш привычный воркфлоу:

CLI-обертка. Самый ленивый вариант. Команда headroom wrap claude запускает Claude Code через прокси Headroom. Работает также с Aider, Copilot CLI и другими популярными агентами.
Локальный прокси. Запускаете headroom proxy --port 8787 и меняете base_url в настройках своего OpenAI или Anthropic клиента. Весь трафик пойдет через сжиматель автоматически.
Библиотека. Если вы пишете свое приложение на Python или TypeScript, можно просто импортировать функцию compress и прогнать через нее массив сообщений перед отправкой.
MCP сервер. Для тех, кто уже перекатился на Model Context Protocol, Headroom предлагает готовые инструменты headroom_compress и headroom_retrieve.

Как устроено сжатие внутри

Вместо того чтобы просто обрезать текст (как делают многие наивные реализации), Headroom использует цепочку специализированных трансформеров:

SmartCrusher — «давит» JSON. Он умеет находить повторяющиеся структуры в массивах объектов и схлопывать их, оставляя только важные данные.
CodeCompressor — понимает синтаксическое дерево (AST) для Python, JS, Go и других языков. Он может выкинуть детали реализации функций, оставив только сигнатуры, если модель просто «осматривается» в проекте.
Kompress-base — собственная модель на HuggingFace, обученная специально на логах работы AI-агентов. Она сокращает естественный язык, сохраняя семантику.
CacheAligner — хитрая штука, которая следит за тем, чтобы префиксы промптов оставались стабильными. Это критично для того, чтобы кэширование на стороне провайдеров (вроде Anthropic Prompt Caching) реально работало и экономило вам деньги.

Интересная фишка — архитектура CCR (Reversible Compression). Если LLM понимает, что ей не хватает деталей в сжатом тексте, она может вызвать инструмент headroom_retrieve и получить оригинал нужного фрагмента. Оригиналы хранятся у вас локально, так что данные не теряются.

Кому это пригодится на практике

В первую очередь тем, кто живет в терминале и IDE с AI-ассистентами. Если вы часто делаете grep по огромным логам или просите агента проанализировать вывод CI/CD, Headroom окупится за пару дней активной работы.

Второй кейс — сложные RAG-системы. Вместо того чтобы пихать в контекст целые куски документации, их можно «поджать», уместив в один запрос в три раза больше полезной информации.

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

Стоит ли пробовать

Проект выглядит очень живым (больше 6000 звезд на момент написания). Главный плюс — локальность. Ваши данные не улетают на какой-то сторонний «сервис оптимизации», всё сжатие происходит на вашей машине.

Из минусов: проект требует Python 3.10+, и если вы работаете в жестко ограниченных песочницах, где нельзя запускать сторонние процессы, завести прокси будет непросто.

Если счета за токены начали кусаться или вы упираетесь в лимиты контекста — ставьте, пробуйте headroom stats и посмотрите, сколько воздуха в ваших промптах.

pip install "headroom-ai[all]"
headroom wrap claude

Headroom в действии

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