Headroom для Claude Code: как срезать расход токенов на 60-95% в 2026

Каждый раз, когда Claude Code лезет в файл, в лог или в длинную историю переписки, он отправляет в нейросеть гору текста, за который ты платишь. Половина этого текста модели на самом деле не нужна. Headroom встаёт посередине и сжимает всё лишнее ещё до отправки: до 60-95% меньше токенов на тяжёлых кусках при том же ответе. Код открытый, лицензия Apache-2.0, около 61 тысячи звёзд на GitHub.

Ниже разберём по шагам: что нужно до старта, какую команду вставить, что ты увидишь на экране. Без терминальной магии, понятным языком для человека, который открывает это впервые. К концу у тебя будет обёрнутый Claude Code и дашборд, на котором видно экономию цифрами.

Что такое Headroom и зачем он нужен

Токен - это кусочек текста, которым нейросеть считает и твой вопрос, и всё, что она вокруг него читает: файлы, логи, ответы инструментов, куски базы знаний, историю чата. Чем больше текста едет в модель, тем больше токенов ты жжёшь и тем дороже выходит каждый шаг.

Headroom - это прокси, то есть посредник, который поднимается прямо на твоём компьютере и встаёт между Claude Code и нейросетью. Всё, что Claude собирается отправить, сначала проходит через Headroom. Он выкидывает повторы и воду, сжимает длинные куски и только потом передаёт дальше. В README проекта это сказано одной строкой: сжать ответы инструментов, логи, файлы и куски базы знаний до того, как они дойдут до модели, 60-95% меньше токенов при том же ответе.

Главное тут вот что: сжатие обратимое. Оригиналы Headroom держит у себя в кэше, и если модели вдруг понадобятся полные данные, она их дозапросит. Ты ничего не теряешь, а платишь меньше. Проект открытый, около 61 тысячи звёзд и свободная лицензия Apache-2.0. Дальше ставим по шагам.

Одна честная поправка про проценты. В шапке репозитория цифра стоит с уточнением: около 20% экономии на обычной болтовне кодового агента и 60-95% на JSON, логах и кусках базы знаний. То есть верхняя граница ловится там, где в модель едет много структурного мусора, а не на каждом коротком запросе. Дальше в статье под «60-95%» имеются в виду именно такие тяжёлые куски.

Что нужно до старта: Claude Code и Python

Headroom не работает сам по себе, он оборачивает уже установленный Claude Code. Если его ещё нет, поставь сначала его. Это один вечер и без программирования. Разбор установки для новичка есть тут: Claude Code для не-программистов.

Вторая вещь - Python версии 3.10 или новее. Python это язык, на котором написан Headroom, и заодно среда, через которую он ставится. У большинства он уже стоит вместе с системой, отдельно качать чаще всего не придётся. Как проверить версию и что делать, если она старая, покажу ниже в разделе про грабли.

Ещё один момент по деньгам. Headroom режет расход, но саму подписку Claude ты всё равно оплачиваешь отдельно. Как её оформить и что выбрать под свои задачи, разобрано в гайде про подписку Claude Code.

Шаг 1. Открой страницу проекта на GitHub

Репозиторий - это папка проекта на GitHub, складе открытого кода, куда выкладывают такие штуки. Зайди на страницу по адресу github.com/headroomlabs-ai/headroom. Там видно число звёзд (столько людей отметили проект полезным), лицензию и инструкцию по установке.

Шапка репозитория выглядит примерно так:

headroomlabs-ai / headroom

Compress tool outputs, logs, files, and RAG chunks
before they reach the LLM. 20% fewer tokens for coding
agents, 60-95% fewer tokens for JSON, same answers

★ ~61k звёзд   ⚖ Apache-2.0   язык: Python

Зачем вообще открывать страницу перед установкой: проекты живые, команды иногда меняются. Инструкция в шапке репозитория всегда актуальнее любого гайда. Если что-то не совпадёт с шагами ниже, верь первоисточнику.

Шаг 2. Поставь Headroom одной командой

Открой в VS Code встроенный терминал: верхнее меню Terminal → New Terminal. Терминал это чёрное окошко, куда пишут команды текстом. Вставь команду ниже и нажми Enter.

Это официальный установщик через Python. pip это встроенный магазин пакетов Python, а хвост [all] в квадратных скобках значит «поставь сразу со всем набором», чтобы потом ничего не докачивать.

# ставим Headroom со всем набором
pip install "headroom-ai[all]"

В терминале побегут строки установки, потом появится финальная строка вроде Successfully installed headroom-ai. Это значит, что в системе появилась новая команда headroom, ей мы дальше и пользуемся.

Шаг 3. Оберни Claude Code через Headroom

Теперь самое главное. В том же терминале вставь команду ниже и нажми Enter. Слово wrap значит «оберни», то есть заверни Claude Code в Headroom, а claude это и есть тот самый Claude Code, который мы оборачиваем.

# поднимаем прокси и запускаем Claude Code через него
headroom wrap claude

Headroom поднимет локальный прокси, то есть посредника прямо на твоём компьютере, наружу ничего не уходит. Подцепит к нему Claude Code и запустит твою сессию уже через себя. Внешне это тот же Claude Code, что и раньше, только теперь весь текст к модели идёт через сжатие.

Хочешь убедиться, что всё встало правильно, запусти проверку здоровья (health-check). Открой второй терминал и вставь:

# проверяем, что всё на месте
headroom doctor

Если всё в порядке, doctor отчитается, что прокси на месте и подключение к Claude Code живо.

Как этим пользоваться каждый день

Дальше ничего нового учить не надо. Ты пишешь Claude Code задачи ровно так же, как раньше: попроси собрать страницу, разобрать файл, написать текст. Всё это едет через Headroom, сжимается по пути, а ты просто получаешь ответ. Разница только в счёте за токены.

Чтобы увидеть эту разницу цифрами, открой дашборд, то есть панель экономии в браузере. Запусти команду ниже, и Headroom покажет живой процент сокращения токенов и прикидку экономии в долларах:

# открыть живой дашборд экономии
headroom dashboard

Если браузер открывать лень, глянуть цифры прямо в терминале можно короткой командой headroom savings.

На дашборде сверху общий процент, ниже видно, на чём именно срезаны токены. Схема выглядит примерно так:

Что режется	Экономия по примеру
Ответы инструментов	-95%
Файлы и логи	-88%
История переписки	-70%
Итого по сессии	до 92%

Например, один тяжёлый запрос без Headroom тянул 65 тысяч токенов, а после сжатия ушло около 5 тысяч. Цифры на дашборде это пример экономии, а не гарантия: у тебя выйдет своё число в зависимости от того, сколько повторов и логов гоняет твоя сессия.

Три вещи, на которых спотыкаются новички

Сначала Claude Code, потом Headroom. Headroom нечего оборачивать, если самого Claude Code на компьютере ещё нет. Если headroom wrap claude ругается, что не находит claude, почти всегда дело именно в этом. Вернись к разделу про то, что нужно до старта, и поставь Claude Code.

Проверь версию Python. Нужен Python 3.10 или новее. Набери в терминале python3 --version. Если цифра меньше 3.10 или команду вообще не нашли, скачай свежий Python с официального сайта python.org и поставь. Дальше установка Headroom пойдёт как надо.

Не бойся потери данных, сжатие обратимо. Кажется, что если выкинуть половину текста, модель что-то недопоймёт. Не недопоймёт: оригиналы Headroom держит в кэше, и если модели нужны полные данные, она их дозапросит. Ты режешь счёт за токены, а качество ответа остаётся прежним.

Зачем тебе это на самом деле

Поставить Headroom это полдела, по шагам выше ты сделаешь это сегодня. Дальше начинается интересное.

Пока каждый твой запрос тащит в модель гору лишнего текста, ты упираешься в лимит и в счёт очень быстро: несколько плотных задач, и бюджет на день выгорел. А когда лишнее срезано на 60-95%, тот же самый лимит вдруг тянет в разы больше работы.

Это значит: дольше работаешь без остановки, гоняешь Claude Code по большим проектам, не считая каждый шаг, и перестаёшь платить за повторы, которые модель и так уже видела. Инструмент из «дороговато, надо экономить» превращается в рабочую лошадку, на которой не страшно ехать целый день.

Чек-лист: что у тебя теперь есть

• Claude Code установлен и открывается хотя бы одной рабочей сессией
• Python версии 3.10 или новее проверен командой python3 --version
• Headroom поставлен через pip install "headroom-ai[all]", в терминале была строка Successfully installed
• Claude Code запускается обёрнутым: headroom wrap claude
• Проверка headroom doctor показывает, что прокси на месте
• Дашборд экономии открывается через headroom dashboard, видно живой процент сокращения токенов
• Тот же дневной лимит теперь тянет в разы больше задач без выгорания бюджета