Headroom для Claude Code и Codex: как сжимать контекст и экономить токены AI-агента
Coding-agent быстро накапливает тысячи токенов из grep, логов, результатов тестов, JSON, документации и повторных чтений.
Headroom ставится между агентом и LLM, локально оптимизирует входящий контекст и только после этого
отправляет запрос модели. Для Claude Code, Codex, Cursor и других инструментов есть готовый режим wrap.
Headroom — локальный слой оптимизации контекста перед LLM
Headroom не является языковой моделью и не заменяет Claude Code, Codex или Cursor. Он работает как промежуточный слой: получает сообщения и tool output, определяет тип содержимого, применяет подходящий способ сжатия и передаёт модели более компактный контекст.
Проект предлагает несколько способов интеграции: Python/TypeScript SDK, локальный HTTP proxy, MCP-инструменты
и готовые wrappers для coding-agents. Для обычного пользователя Claude Code или Codex самым понятным вариантом
является headroom wrap ....
Существующий инструмент направляется через локальный Headroom proxy без переписывания приложения.
Headroom сам запускает proxy и настраивает сессию Claude Code, Codex, Aider или другого поддерживаемого клиента.
Приложение может вызвать compress() перед обращением к OpenAI, Anthropic или другому API.
Есть отдельные инструменты восстановления исходного контекста, статистики и межсессионной памяти.
Основной расход контекста coding-agent часто создаёт не ваш вопрос, а результаты инструментов
Агент читает файлы, запускает тесты, выполняет поиск по репозиторию, получает большие JSON-ответы и постоянно добавляет эти результаты в историю. Даже короткая задача может превратиться в десятки тысяч входных токенов.
Каждый tool result идёт в контекст почти целиком
Повторяющиеся строки и одинаковые поля продолжают занимать место, даже если для следующего решения они почти бесполезны.
Контекст сначала проходит через Content Router
JSON, логи, поиск, текст, diff и другие типы данных могут обрабатываться разными алгоритмами.
Для coding workload у проекта включены специальные защиты: актуальные file reads не должны подвергаться lossy-сжатию, потому что агенту нужны точные байты для изменения файла.
Где Headroom экономит много, а где почти ничего
Эффект сильно зависит от структуры данных. Однотипные массивы, логи и документация содержат много повторов, а уже плотный исходный код сжимать рискованно.
| Тип содержимого | Результат benchmark 0.37.0 | Практический смысл |
|---|---|---|
| JSON search results, 100 элементов | около 48% | Повторяющаяся структура позволяет убрать значительную часть токенов. |
| JSON search results, 500 элементов | около 49% | Экономия сохраняется и на более крупном массиве. |
| Structured logs, 500 записей | около 54% | Однотипные записи хорошо подходят для структурного сжатия. |
| Документация, ~20K tokens | около 92% | Длинный текст в синтетическом сценарии сократился особенно сильно. |
| Python source, ~200 строк | 0% | В этом тесте SmartCrusher пропустил код без изменений ради корректности. |
Это результат конкретного длинного документа в benchmark. На реальном смешанном контексте процент может быть намного меньше, а плотный код вообще может пройти без сжатия.
Профиль coding специально настроен так, чтобы не ломать работу с кодом и prompt cache
В актуальной конфигурации Headroom профиль coding используется по умолчанию для agent wrapping.
Его цель — не максимальная компрессия любой ценой, а экономия без постоянного разрушения prefix cache и без lossy-сжатия
актуальных чтений файлов.
Сжимается главным образом новый delta-контекст, а уже стабильный префикс стараются не менять.
Горячая часть контекста не переписывается без необходимости, что помогает provider prefix caching.
В coding profile чтение файла не должно lossy-сжиматься: агенту могут понадобиться точные строки для patch.
Сначала применяются безопасные структурные способы, а lossy fallback используется там, где это допускает профиль.
Документация прямо называет показатель emergent: фактический результат зависит от конкретного содержимого.
CCR: если агенту понадобилась удалённая деталь, исходник можно запросить обратно
Один из механизмов Headroom называется Compress-Cache-Retrieve. При сжатии исходные данные сохраняются
локально, а в контекст можно добавить возможность восстановить оригинал через headroom_retrieve.
В proxy штатным persistent backend для CCR является SQLite. Есть и memory backend. Поэтому reversible здесь означает, что удалённое из текущего prompt содержимое не обязано быть потеряно навсегда.
Модель должна понять, что ей не хватает деталей, и воспользоваться механизмом восстановления. Отдельные режимы также могут отключать CCR или использовать lossless-only поведение.
Актуальный README уже не обещает одинаковые 90% на каждом workload
В текущем README проекта опубликована воспроизводимая таблица с четырьмя workload-сценариями. Это полезнее одной общей цифры: видно, насколько результат зависит от структуры данных.
| Сценарий | До | После | Экономия |
|---|---|---|---|
| Code search, 100 results | 17 199 | 13 597 | 21% |
| SRE incident debugging | 55 957 | 24 340 | 57% |
| Codebase exploration | 58 801 | 33 895 | 42% |
| GitHub issue triage | 46 067 | 32 429 | 30% |
Отдельный latency benchmark Headroom 0.37.0 показывает суммарное сокращение 126 400 → 55 100 tokens, то есть около 56%, на наборе JSON, логов, документации и Python-кода. Но это синтетический смешанный набор, а не одна реальная coding-session.
В текущей документации methodology стала аккуратнее: например, для SQuAD LLM-graded QA прямо указано, что committed result artifact отсутствует и универсальная цифра не публикуется.
Как запустить Headroom с Claude Code или Codex
Для CLI проект рекомендует Python-пакет. NPM-пакет даёт TypeScript SDK, но не команду headroom.
Headroom требует Python 3.10+, а в quickstart для uv сейчас используется Python 3.13.
Через uv
uv tool install --python 3.13 "headroom-ai[all]"
headroom --versionЗапустить через wrapper
headroom wrap claudeHeadroom запускает локальный proxy и стартует Claude Code через него.
Аналогичный wrapper
headroom wrap codexАргументы Codex можно передавать дальше после --.
Запустить proxy и получить настройки
headroom wrap cursorCursor не запускается автоматически: команда выводит base URL, который нужно указать в настройках модели.
Doctor и статистика
headroom doctor
headroom perfТак можно проверить routing и увидеть фактическую экономию на своих запросах.
Без agent wrapper
headroom proxy --port 8787Подходит для приложений и клиентов, которые умеют работать с собственным base URL.
Headroom имеет собственные команды статистики и savings, поэтому эффект можно проверить на реальных сессиях.
Coding, balanced, agent-90 и general — разные задачи требуют разной агрессивности
Cache mode, сохранение system prompt, защита file reads, оптимизация под coding-agent.
Token mode с более заметной компрессией и защитой нескольких последних turns.
Агрессивный режим с ML-based Kompress и keep-ratio 0.10. Не основной выбор для кода.
Общий режим для не-кодовых разговоров и контекста.
HEADROOM_SAVINGS_PROFILE=coding headroom proxy
HEADROOM_SAVINGS_PROFILE=balanced headroom proxy
HEADROOM_SAVINGS_PROFILE=agent-90 headroom proxyДаже документация называет часть значений emergent. Реальная экономия определяется тем, что именно читает агент.
Headroom локально сжимает контекст, но это не превращает облачный Claude или OpenAI в локальный ИИ
README проекта указывает, что само сжатие выполняется на вашей машине и содержимое не отправляется отдельному внешнему сервису для компрессии. Это плюс с точки зрения архитектуры.
Компрессия, локальный proxy, CCR store и часть служебной обработки Headroom.
Оптимизированный prompt отправляется тому LLM-провайдеру, который настроен в Claude Code, Codex или вашем приложении.
Поэтому Headroom нельзя описывать как средство полной локальности или как замену Ollama/llama.cpp. Он оптимизирует путь к выбранной модели. Если backend облачный, обработка самой LLM остаётся облачной.
Когда Headroom почти не поможет или потребует осторожной настройки
Из-за safety-защит он часто проходит без заметного сжатия, и это сделано намеренно.
Если tool output и так маленький, экономить практически нечего.
Чем меньше повторов и boilerplate, тем меньше эффект.
Kompress требует дополнительных зависимостей и может добавлять latency.
Если сам агент уже агрессивно суммаризирует контекст, второй слой нужно тестировать отдельно.
Benchmark проекта нельзя автоматически переносить на другой агент, модель и репозиторий.
Не стоит начинать с agent-90 только ради красивой цифры экономии.
Headroom и Ponytail решают разные уровни одной проблемы
Уменьшает то, что агент строит
YAGNI, reuse, stdlib и native capabilities вместо лишних abstractions и зависимостей.
Уменьшает то, что агент читает
Сжимает tool output, логи, JSON, старые результаты и часть контекста до отправки модели.
Эти проекты не являются прямыми конкурентами. Теоретически их можно использовать вместе: Ponytail ограничивает переусложнение реализации, а Headroom контролирует рост контекстного окна и расход входных токенов.
Исходники, benchmark и документация Headroom
Headroom быстро развивается. Перед копированием команд проверьте актуальный README и headroom <cmd> --help.
Headroom имеет смысл там, где агент действительно тонет в tool output
Для короткой сессии с парой файлов дополнительный proxy может не дать заметного выигрыша. Но при больших grep-выводах, логах, JSON, длительных multi-turn сессиях и частом использовании инструментов идея локальной оптимизации контекста выглядит практически полезной.
Самое важное — не ориентироваться на максимальные проценты. Текущий README проекта сам показывает диапазон 21–57% на четырёх workload-сценариях, а benchmark исходного кода демонстрирует 0% для одного из code-сценариев. Headroom лучше воспринимать как инженерный инструмент, который надо измерять на своей нагрузке, а не как универсальную кнопку «минус 90% токенов».
Частые вопросы о Headroom
Что такое Headroom простыми словами?
Локальный слой между AI-клиентом и моделью, который пытается уменьшить лишний контекст до отправки LLM.
Headroom работает с Claude Code?
Да. Для этого есть команда headroom wrap claude и coding profile, рассчитанный на coding-agent workloads.
Можно ли использовать Headroom с OpenAI Codex?
Да. В CLI предусмотрен headroom wrap codex.
Он действительно экономит 90% токенов?
Иногда на очень повторяющемся содержимом. На текущих workload-примерах README экономия составляет примерно 21–57%, а на плотном коде может быть близка к нулю.
Headroom отправляет мои файлы на свой сервер?
Проект заявляет локальную компрессию. Но итоговый оптимизированный запрос всё равно отправляется выбранному LLM-провайдеру, если сама модель облачная.
Что такое CCR?
Compress-Cache-Retrieve: оригинал сохраняется локально, а модель может запросить полный фрагмент, если сжатой версии недостаточно.
Headroom заменяет Ponytail?
Нет. Ponytail уменьшает лишнюю реализацию, Headroom уменьшает лишний контекст. Это разные уровни оптимизации.
С какого режима начать?
Для Claude Code, Codex и Cursor логичнее начинать со стандартного coding profile и измерять реальную экономию.
Нужно разобраться с локальным ИИ, AI-агентом или рабочим окружением?
Можно прислать конфигурацию ПК, используемые модели и задачу. Разберём, что имеет смысл запускать локально, где нужен облачный backend и какие инструменты действительно дают пользу.