Headroom: как сжимать контекст агента и платить меньше за токены
Агент платит за каждый токен, который прочитал: логи, JSON, файлы, историю сессии. Headroom сжимает это локально до отправки в модель — от 21% до 57% на реальных сценариях, с возможностью вернуть оригинал.
ГайдКонтекстЭкономия токенов
Уровень СреднийВремя настройки 10–20 минутЛицензия Apache-2.0Обновлено 08.11.2026
Результат гайда: вы включаете сжатие контекста за десять минут — одной командой для coding-агента или парой строк кода для своего приложения — и видите, сколько токенов реально экономится на вашем трафике, а не в чужом бенчмарке.
Перед началом
Нужен Python 3.11+ или Node.js 18+, если ставите SDK. Сжатие работает на вашей машине: ни промпты, ни файлы наружу не отправляются. Для полностью офлайнового прогона есть HEADROOM_OFFLINE=1.
01Зачем сжимать контекст и что именно болит
Большая часть счёта coding-агента — это не ответы, а чтение: вывод тестов, ответы MCP-серверов, куски файлов, история правок. Полезная строка в логе обычно одна (та самая FATAL), а платите вы за десять тысяч токенов вокруг неё.
Headroom ставит между агентом и провайдером локальный слой, который переписывает входной контекст: режет повторы в JSON-массивах, выкидывает шаблонные строки логов, ужимает историю сессии. Оригиналы остаются на диске, и модель может запросить полный текст инструментом headroom_retrieve — то есть сжатие обратимое.
Реклама. ООО «КАПИБАРА», ИНН 9703231520
Из чего состоит контекст агента
Типовая структура входа coding-агента по описанию проекта: три четверти контекста — служебные данные, а не задача.
Экономия не бесплатна по смыслу: любое сжатие — это ставка на то, что деталь не понадобится. Поэтому в гайде отдельный раздел про замеры точности и про то, где сжатие почти не работает — на связной прозе и уже плотном тексте.
02Как устроено: четыре узла и хранилище оригиналов
Слои обработки запроса
Путь одного запроса
Ключевая деталь — маршрутизация по типу. JSON-массивы и логи сжимаются на 90%+, а связная проза почти не поддаётся: если бы компрессор был один на всё, экономия на документации съедалась бы риском потерять смысл.
Кэш важнее процентов
Провайдеры дают скидку за повторное использование префикса промпта. Если сжатие меняет префикс на каждом запросе, выигрыш на токенах съедается потерей кэша — поэтому CacheAligner не «улучшает» промпт, а только помечает волатильные участки.
03Установка за 60 секунд
От установки до первого отчёта
1
Поставьте CLI
Изолированное окружение через uv — основной способ из README; pip тоже работает и приносит команду headroom.
doctor подтверждает, что маршрутизация и сжатие работают, perf показывает скорость обработки.
terminalcopy
headroom doctor && headroom perf
4
Смотрите цифры
dashboard открывает локальную панель с экономией; savings считает по вашему трафику.
terminalcopy
headroom savings
Для своего приложения установка проще: pip install headroom-ai, затем from headroom import compress. Функция принимает список сообщений в формате OpenAI или Anthropic, возвращает объект с полями messages, tokens_saved и compression_ratio — второй аргумент model= нужен для правильного токенизатора.
CLI только в PyPI-пакете
npm-пакет headroom-ai — это TypeScript SDK без команды headroom. Если приложение на Node, SDK отправляет сообщения в локальный прокси, который поднимается отдельно: pip install "headroom-ai[proxy]" и headroom proxy --port 8787.
04Три режима и когда какой брать
Режим
Как включается
Кому подходит
Минусы
Библиотека
compress(messages, model=...)
Свой код на Python или TS
Правки в коде приложения
Прокси
headroom proxy --port 8787
Любой клиент, включая TS и Go
Нужен запущенный процесс
Wrap агента
headroom wrap claude
Coding-агенты без изменений кода
Живёт только на время сессии
MCP-сервер
headroom mcp install
MCP-нативные клиенты
Меньше контроля над потоком
Режимы комбинируются: wrap поднимает прокси сам, а библиотека может ходить в тот же процесс.
Wrap поддерживает два десятка агентов: Claude Code, Codex, Grok CLI, Aider, Copilot CLI, VS Code Copilot, OpenCode, Cline, Continue, Goose, OpenHands, Kimi CLI, Factory Droid, ZCode и другие. Для Cursor настройка ручная — прокси печатает базовые адреса, которые нужно вписать в настройки. Cortex Code работает только как библиотека.
Отмена durable-обёртки — одна команда headroom unwrap <tool>. Это важно для тех, кто пробует инструмент на рабочей машине: конфиги агента возвращаются в исходное состояние, а не остаются с прописанным адресом прокси.
Свой код: минимальный пример
1
Импорт и сжатие
Сжимаются сообщения инструментов и ассистента; сообщения пользователя не трогаются без явного флага.
app.pycopy
from headroom import compress
r = compress(msgs, model="gpt-4o")
print(r.tokens_saved, r.compression_ratio)
2
Отправка в модель
В провайдер уходит r.messages — обычный вызов, без правок клиента и без ключа Headroom.
По умолчанию wrap отправляет OpenAI-трафик на api.openai.com. Для DeepSeek, OpenRouter или своего шлюза передайте --openai-api-url (или переменную OPENAI_TARGET_API_URL), иначе ключ уйдёт не туда и вернётся 401.
05Что реально экономит: замеры проекта
В README опубликованы четыре сценария, собранные из реальных форматов вывода MCP-серверов, с провайдерским токенизатором и тем же compress(), что ставится из пакета. Замеры воспроизводимы: uv run python benchmarks/index_proof_table.py --seed 20260902.
Токены до и после сжатиячетыре сценария, данные авторов
Сценарии построены на форматах вывода MCP-серверов, а не на живом трафике конкретной команды.
Доля сэкономленных входных токенов%, чем длиннее повторы, тем выше экономия
Данные авторов проекта на 08.11.2026. На вашем трафике цифра будет другой — её показывает команда headroom savings.
Обратите внимание на разброс: 21% на поиске по коду и 57% на разборе инцидента — это один и тот же компрессор на разных данных. Повторяющиеся JSON-массивы и строки логов уходят за 90%, а плотная проза почти не сжимается. Отсюда вывод: включать сжатие стоит там, где агент много читает машинного вывода.
Разработка Headroom по неделямкоммитов в неделю, последние 16 недель, снято 08.11.2026
Источник — stats/participation GitHub API. Ровный темп без «мёртвых» недель: проект активно развивается.
06Не теряет ли модель смысл: точность и скорость
В репозитории есть набор проверок точности: python -m headroom.evals suite --tier 1. Цифры ниже — из README, на выборке 100 задач; при таком N изменение ±0,03 статистически неотличимо от нуля, и авторы честно пишут, что TruthfulQA не улучшилась, а «не показала разницы».
Бенчмарк
Что мерит
Базовая линия
С Headroom
Разница
GSM8K
Школьная математика
0,870
0,870
±0,000
TruthfulQA
Фактологичность
0,530
0,560
+0,030
SQuAD v2
Вопросы по тексту
—
97%
при 19% сжатия
BFCL
Вызов инструментов
—
97%
при 32% сжатия
Данные авторов проекта, N=100 на бенчмарк. Для продакшена важнее свой замер на своих задачах.
Скорость сжатия — доли миллисекунды: 0,21 мс p50 на JSON-результате в 10 тыс. токенов и 1,4 мс на 100 тысячах. То есть на задержку агента это не влияет — в отличие от лишнего сетевого хопа к стороннему сервису сжатия.
Обратимость — главный аргумент
Сжатие не «выбрасывает» данные: оригинал лежит в локальном хранилище CCR, и модель может забрать полный текст инструментом headroom_retrieve. Поэтому редкая деталь не теряется навсегда — её просто не отправляют в контекст заранее.
Для команд важнее другое: headroom learn разбирает проваливавшиеся сессии и дописывает поправки в CLAUDE.local.md, AGENTS.md или GEMINI.md. Это уже не про токены, а про то, чтобы агент не повторял одну и ту же ошибку в следующей сессии.
07Ограничения, приватность и тарифы
Прозу и уже плотный текст сжатие почти не уменьшает — ждать 50% на документации не стоит.
Компрессор текста тянет модель Kompress-v2-base с HuggingFace: первый запуск требует загрузки, в закрытом контуре нужен HF_ENDPOINT и предварительная загрузка.
Телеметрия включена по умолчанию: отправляются коэффициенты сжатия и ID моделей, но не промпты и не код. Отключается HEADROOM_TELEMETRY=off или DO_NOT_TRACK=1.
Прокси — дополнительный процесс в цепочке: падение прокси останавливает агента, поэтому для продакшена нужен persistent-вариант через headroom deploy.
На Anthropic-пути режим cache отключает автоматическую инъекцию памяти — иначе ломается префикс кэша; память тогда включают режимом token.
оптимально
Open Source
0 ₽Apache-2.0
Библиотека, прокси, wrap
MCP-сервер и память
Локальное сжатие без лимитов
Enterprise
по запросуHeadroom Labs
Развёртывание on premise
Атрибуция расходов
Расширенная экономия
Свой замер
0 ₽headroom savings
Отчёт по вашему трафику
Панель dashboard
Без отправки данных наружу
Цены на 08.11.2026: открытая версия бесплатна, коммерческие условия Enterprise вендор публикует только по запросу — уточняйте на headroomlabs.ai.
Публичного прайса Enterprise нет; в README указан контакт hello@headroomlabs.ai.
Практический порядок внедрения: сначала замерьте baseline на своей задаче (сколько токенов уходит на типовую сессию), затем включите wrap на одном агенте, неделю смотрите отчёты и только после этого добавляйте сжатие в общий пайплайн. Так решение опирается на ваши цифры, а не на чужие проценты.
Итог гайда
8,8/ 10
Настройка занимает десять минут, работает локально, обратима и не добавляет задержки. Главное ограничение — экономия зависит от типа контекста: много выигрывают агенты, которые читают логи и JSON, почти ничего не получают те, кто работает с прозой.
Нет. Сжатие идёт в вашем процессе или в локальном прокси; оригиналы хранятся локально в CCR. Модель Kompress-v2-base скачивается один раз, дальнейшая работа возможна с HEADROOM_OFFLINE=1.
Сколько токенов экономится в реальности?
На четырёх сценариях авторов — от 21% до 57% входных токенов; на повторяющихся JSON-массивах и логах — 90%+. На прозе почти ноль, поэтому точную цифру для своего трафика даёт headroom savings.
Нужно ли менять код приложения?
Нет, если использовать прокси или wrap: агент просто ходит через локальный порт. Библиотека нужна, когда вы хотите сжимать сообщения в своём коде до вызова API.
Совместимо ли с Claude Code и Codex?
Да, это основные поддерживаемые агенты: headroom wrap claude и headroom wrap codex поднимают прокси и запускают агент с нужными настройками; отмена — headroom unwrap.
Сломает ли сжатие качество ответов?
По замерам авторов на GSM8K разницы нет, на TruthfulQA изменение в пределах погрешности, на SQuAD v2 и BFCL точность 97% при сжатии 19–32%. Для критичных задач проверяйте на своей выборке.
Что будет, если агенту понадобится сжатый фрагмент целиком?
Он запросит его инструментом headroom_retrieve: оригинал сохранён локально, поэтому сжатие не уничтожает данные, а только убирает их из отправляемого контекста.