Headroom: как срезать расход токенов в Claude Code и замерить эффект у себя

Сначала факты: что подтвердилось, а где цифры завышены

Я специально свёл заявления из роликов с тем, что написано в официальном репозитории, потому что ты пойдёшь ставить это себе и должен понимать, чего реально ждать.

Инструмент существует и называется именно Headroom. Официальный репозиторий это headroomlabs-ai/headroom, лицензия Apache 2.0, ядро полностью открыто и бесплатно, платить за установку и работу не нужно. Пакет называется headroom-ai, написан на Python. Здесь всё сходится с тем, что рассказывают в роликах.

Что вообще происходит внутри

Понимание механики займёт минуту и сэкономит тебе часы разбирательств, когда что-то пойдёт не так.

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

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

Отдельная приятная деталь в том, что Headroom старается не ломать кеширование на стороне провайдера. Он сжимает только свежие куски, а уже отправленную ранее часть диалога оставляет байт в байт прежней, чтобы кеш продолжал срабатывать. Это важно, потому что наивное сжатие всего подряд иногда обходится дороже, чем отсутствие сжатия вообще.

Установка по шагам

Все команды ниже вводятся в терминале, а не в окне диалога с Claude. На Windows работай в терминале WSL, проект рассчитан на среду Linux и macOS.

Шаг 0. Проверь, что подходит машина

Нужен Python версии 3.10 или свежее, авторы рекомендуют 3.13. Процессор должен быть обычным современным x86 либо Apple Silicon, на редких старых процессорах часть ускорений отключится и проект перейдёт на запасной режим. Проверь версию Python командой ниже, и если она младше 3.10, сначала обнови Python.

В ответ должно появиться что-то вроде Python 3.13.1. Если терминал ругается, что команда не найдена, ставь Python с официального сайта и возвращайся сюда.

Шаг 1. Поставь Headroom

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

Если uv не установлен, бери вариант через pip:

Шаг 2. Убедись, что команда появилась

После установки в системе должна появиться команда headroom. Проверь так:

В ответ терминал выведет список доступных команд. Набор команд немного отличается от версии к версии, проект развивается быстро, поэтому ориентируйся на то, что реально показал твой вывод, а не на список из любой статьи, включая эту. Если команда не найдена, иди в раздел про типовые ошибки, там разобран этот случай.

Шаг 3. Запусти Claude Code через Headroom

Вот та самая команда, ради которой всё затевалось. Она поднимает локальный прокси, прописывает Claude Code маршрут через него и запускает сам Claude Code.

Дальше ты работаешь в Claude Code ровно как раньше, ничего нового учить не нужно. Прокси по умолчанию слушает порт 8787 на твоей машине, наружу ничего не уходит, весь разбор происходит локально.

Как убедиться, что оно реально работает

Самая частая ошибка новичка выглядит так: человек поставил инструмент, запустил Claude Code по старой привычке и через неделю говорит, что не работает.

1. Проверь, что прокси поднялся. Пока Claude Code работает через обёртку, порт 8787 должен быть занят. Команда для проверки идёт следующим блоком.
2. Посмотри стартовые строки. При запуске обёртка печатает, что прокси стартовал и что конфигурация агента обновлена. Если таких строк нет и Claude Code открылся мгновенно, значит обёртка не отработала.
3. Прогони любую тяжёлую задачу. Попроси Claude Code прочитать несколько крупных файлов или прогнать поиск по проекту, чтобы через прокси прошёл заметный объём данных. На пустом диалоге сравнивать нечего.
4. Открой сводку по производительности. В большинстве версий это команда headroom perf, она собирает статистику из логов прокси и показывает, сколько прошло и сколько сжалось.

Если в ответ появилась строка с процессом, прокси живой. Пустой ответ означает, что прокси не запущен и Claude Code сейчас ходит в модель напрямую.

Команда покажет сводку за последние сутки. В некоторых версиях рядом живут ещё команды со сводкой по экономии и health-проверкой окружения, посмотри их наличие в выводе headroom --help и пользуйся тем, что есть у тебя.

Замер расхода токенов до и после

Это единственный способ узнать правду про экономию именно на твоих задачах. Займёт двадцать минут, зато дальше ты будешь говорить цифрами.

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

Шаг 1. Сделай замер до установки

Открой Claude Code обычным способом, без обёртки. Внутри диалога есть служебная команда, которая показывает расход по текущей сессии, набери её прямо в окне Claude Code:

Запиши цифру. Затем выполни свою типовую рабочую задачу, что-то реальное из твоей практики, например попроси разобраться в проекте и внести небольшую правку. Когда закончишь, набери /cost ещё раз и запиши, во сколько обошлась сессия целиком. Это твоя базовая цифра.

Шаг 2. Сделай тот же прогон через Headroom

Закрой Claude Code, запусти его через обёртку командой headroom wrap claude и повтори ту же самую задачу теми же словами, на том же проекте. В конце снова посмотри /cost. Разница между двумя цифрами и есть твоя реальная экономия.

Шаг 3. Не обмани себя

• Один прогон ничего не доказывает. Расход прыгает даже на одинаковых задачах, потому что модель каждый раз выбирает чуть разный путь. Сделай три пары прогонов и смотри на среднее.
• Сравнивай похожее с похожим. Если во втором прогоне Claude полез в другие файлы, замер испорчен, повтори.
• Проверь на своей типичной работе, а не на искусственно тяжёлой. Если ты специально скормишь ему гигантский JSON, увидишь красивые 90 процентов, которые к твоим будням отношения не имеют.
• Смотри не только на деньги, но и на то, как быстро забивается окно контекста. Часто главная выгода в том, что диалог дольше живёт без сброса, и это ощущается сильнее экономии.

Что режется и когда это мешает

Любое сжатие это компромисс. Здесь честно про то, где он может выйти боком, чтобы ты понимал, когда обёртку лучше выключить.

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

Настройка под себя

Из коробки всё работает без единой настройки. Эти ручки трогай только тогда, когда упрёшься в конкретную проблему.

Подрезать многословие модели

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

Это первое, что стоит попробовать новичку после базовой установки, потому что выходные токены обычно дороже входных, и эффект от этой одной переменной бывает заметнее всего остального.

Сменить порт

Если порт 8787 у тебя уже занят другой программой, задай свой:

Отключить проверку обновлений

Полезно на слабом интернете, чтобы запуск не подвисал:

Работа за корпоративным прокси

Если сеть на работе подменяет сертификаты и запуск падает на проверке, есть послабление строгой проверки. Понимай, что ты ослабляешь защиту соединения, и включай это только в сети, которой доверяешь:

Если не заработало

Собрал типовые места, где спотыкаются, и что делать в каждом.

Если ничего из перечисленного не подошло, запусти обёртку в подробном режиме и прочитай, на каком шаге всё встало. Обычно текст ошибки прямо называет причину.

Готовые команды под типовые сценарии

Три связки, которые закрывают большинство ситуаций. Копируй целиком в терминал.

Сценарий 1. Обычный рабочий день

Максимальная экономия на повседневной работе: сжатие входа плюс подрезка многословия на выходе. Это твой основной режим, положи команду в закладки.

Сценарий 2. Тонкая отладка

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

Сценарий 3. Проверка результата за сутки

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

Промпт для самого Claude Code

Отдельный приём, который работает независимо от Headroom. Дай эту инструкцию в начале рабочей сессии, и Claude станет заметно экономнее обращаться с контекстом.

Экономия токенов в Claude Code без всяких инструментов

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

1. Начинай новый диалог под каждую задачу. Самая дорогая привычка это тащить один бесконечный диалог через весь день, потому что вся история едет в модель на каждом шаге. Закончил задачу, открыл чистую сессию.
2. Следи за окном контекста и чисти его вовремя. Когда индикатор заполнения подбирается к пределу, каждый следующий запрос стоит дороже предыдущего. Сжимай диалог или начинай заново, не дожидаясь, пока он забьётся полностью.
3. Заведи файл памяти проекта. Правила, стек, структура и твои предпочтения, записанные один раз в файл CLAUDE.md, снимают необходимость объяснять контекст в каждом диалоге. Держи его коротким, он читается при каждом старте и сам стоит токенов.
4. Говори конкретными путями. Фраза «поправь функцию отправки в файле src/api/send.py» экономит десятки тысяч токенов по сравнению с «найди, где у нас отправка, и поправь», потому что во втором случае Claude пойдёт перебирать проект.
5. Отключи неиспользуемые MCP-серверы. Описания всех подключённых инструментов загружаются в начале каждой сессии и висят в контексте постоянно. Три лишних сервера, которыми ты не пользуешься, это фиксированный налог на каждый твой запрос.
6. Держи закрытыми лишние вкладки и файлы в редакторе, если работаешь через интеграцию с IDE. Открытые файлы часто подтягиваются в контекст автоматически.
7. Не проси показывать код целиком. Формулируй так: «покажи только изменённые строки». Выходные токены обычно дороже входных, и многословие в ответах бьёт по кошельку сильнее, чем кажется.
8. Разбивай большую задачу на шаги в разных сессиях. Одна сессия на разбор проблемы, вторая на реализацию, третья на тесты. Каждая стартует с чистым контекстом, и суммарно это выходит дешевле одного марафона.

План на первый вечер

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

1. Сделай замер до. Открой Claude Code обычным способом, выполни свою типовую задачу, посмотри /cost и запиши цифру в заметку. Без этого шага весь остальной вечер бессмысленный, сравнивать будет не с чем.
2. Поставь Headroom одной командой через uv, проверь, что команда headroom отзывается на --help.
3. Запусти Claude Code через обёртку и повтори ту же самую задачу теми же словами. Посмотри /cost и запиши вторую цифру.
4. Сравни. Если разница есть, оставляй и переходи на обёртку постоянно. Если разницы нет, посмотри на характер своих задач, скорее всего у тебя мало тяжёлого машинного вывода, и тебе больше дадут приёмы из предыдущего раздела.
5. Через пару дней добавь переменную HEADROOM_OUTPUT_SHAPER=1 и сделай ещё один замер. Это отдельный слой экономии, и его стоит оценить отдельно от базового.