Как урезать расходы на LLM агентов без потери качества
Когда запускаешь Claude Code, Cursor или любого другого автономного кодинг-ассистента в большом репозитории, контекстное окно забивается со страшной скоростью. Вызовы grep, чтение JSON-манифестов, логи тестов и сырые дампы ошибок быстро съедают десятки тысяч токенов за один прогон. В итоге счет за API в конце месяца неприятно удивляет, а сам агент начинает путаться в гигантской простыне данных.
Разработчики из Headroom Labs выложили в открытый доступ Headroom — локальный слой сжатия контекста. Он перехватывает весь поток информации до отправки в модель и аккуратно убирает лишнее.
https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/HeadroomDemo-Fast.gif
Зачем сжимать контекст перед отправкой
Обычно разработчики пробуют бороться с раздуванием контекста банальным урезанием истории или грубым транкейтингом. Но если просто отрезать кусок лога или файла, модель потеряет важный трейс ошибки или сигнатуру функции.
Headroom работает иначе. Он анализирует тип входящих данных и применяет специализированные методы сжатия:
- Для JSON запускается SmartCrusher, который сжимает массивы объектов и вложенные структуры на 60–95%, убирая синтаксический шум и повторяющиеся ключи.
- Исходный код разбирается через AST (поддерживаются Python, TypeScript, Go, Rust, Java, C/C++, Perl), сохраняя структуру и выкидывая лишние детали.
- Обычный текст и логи прогоняются через компактную ML-модель Kompress-v2-base.
- Изображения оптимизируются через встроенный визуальный роутер.
Самое приятное тут в обратимости процесса (CCR, Cached Context Retrieval). Исходные данные никуда не исчезают, а сохраняются в локальном кэше. Если LLM понимает, что ей нужен полный текст конкретного фрагмента, она вызывает инструмент headroom_retrieve и получает оригинал.
Как запустить утилиту за пару минут
Headroom написан на Python с Rust-ядром. Ставить его удобнее всего через uv:
uv tool install --python 3.13 "headroom-ai[all]"
После установки есть несколько способов интеграции.
Обертка над готовым агентом
Если вы используете Claude Code, Aider, Cline или Copilot CLI, можно не менять конфиги вручную:
headroom wrap claude
Команда поднимает локальный прокси, прописывает нужные переменные окружения и запускает сессию агента. Когда работа закончена, вернуть всё назад можно через headroom unwrap claude.
Локальный прокси для любых инструментов
Для Cursor, VS Code или самописных скриптов поднимается универсальный прокси:
headroom proxy --port 8787
Прокси совместим с форматами OpenAI и Anthropic. Вы просто меняете base_url в своем клиенте на http://localhost:8787/v1, и трафик начинает сжиматься на лету. Данные обрабатываются прямо на вашей машине и не уходят на сторонние сервера оптимизаторов.
Использование как библиотеки
В коде на Python или TypeScript утилиту можно вызвать напрямую:
from headroom import compress
compressed_messages = compress(messages, model="claude-3-7-sonnet")
Экономия не только на входе, но и на выходе
Входные токены — это половина беды. Генерация ответа моделями уровня Opus стоит заметно дороже промпта. При этом модели часто тратят выходные токены на пустые вводные фразы, повторный вывод уже показанного кода или избыточные цепочки рассуждений на тривиальных шагах вроде чтения файла.
Headroom умеет управлять и этим:
- Корректирует системный промпт в конце цепочки, призывая модель отвечать кратко и без лишних предисловий.
- Автоматически снижает уровень reasoning effort (
thinking.budget_tokensу Anthropic илиreasoning_effortу OpenAI), когда агент просто считывает результат команды терминала, возвращая полный бюджет на сложных вопросах и ошибках.
Чтобы включить эту механику, достаточно передать переменную окружения:
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787
Посмотреть реальную статистику экономии можно встроенной командой:
headroom dashboard
Работа над ошибками с помощью headroom learn
https://raw.githubusercontent.com/headroomlabs-ai/headroom/main/headroom_learn.gif
В репозиторий встроена интересная утилита:
headroom learn
Она сканирует историю неудачных сессий агента, находит места, где модель застряла или допустила глупую ошибку, и формирует краткие инструкции для исправления. Эти правила автоматически дописываются в локальный CLAUDE.local.md или AGENTS.md. В следующих сессиях агент учитывает прошлый негативный опыт и реже наступает на те же грабли.
В сухом остатке
Headroom пригодится тем, кто регулярно гоняет тяжелые задачи через кодинг-агентов или строит RAG-пайплайны с объемными JSON-ответами и логами.
Сильные стороны проекта:
- Полностью локальная работа без отправки ваших промптов на промежуточные облачные сервисы.
- Готовые обертки для полутора десятков популярных CLI-агентов.
- Поддержка протокола MCP.
- Обратимость сжатия, благодаря которой точность ответов на тестах практически не проседает.
Из нюансов: сборка зависимостей тянет за собой ONNX Runtime, для которого на x86-процессорах требуются инструкции AVX2. На старых виртуальных машинах без AVX2 часть нейросетевых фич отключится, хотя эвристическое сжатие и базовые алгоритмы продолжат работать.
Если хочется сократить затраты на токены в повседневной разработке, поставьте CLI и запустите headroom wrap на своем привычном агенте. Разница в расходе токенов будет видна в дашборде уже после первого часа активной работы.
