agentburn — локальный профайлер расхода токенов AI-агентов

agentburn — локальный CLI-профайлер, который объясняет, где именно AI-агент расходует токены. Он читает журналы Claude Code, OpenCode, Codex CLI, Gemini CLI, OpenClaw и Hermes Agent, приводит их к общей модели и разделяет два сценария: исчерпание окна подписки и списание денег при оплате по токенам. Утилита работает на Python 3.9+, не требует зависимостей и не отправляет содержимое локальных журналов в сеть.

Быстрый старт

Проще всего запустить проект через uvx:

uvx agentburn
uvx agentburn limits
uvx agentburn context

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

Есть аналогичные команды для анализа конкретных источников расхода и подготовки изменений:

uvx agentburn why
uvx agentburn fix
uvx agentburn commits

Когда заканчиваются окна подписки

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

Отчёт разбивает окно по нескольким признакам:

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

Для Claude Code инструмент не придумывает нормативный лимит Anthropic. Вместо этого он находит в транскриптах сообщения о достижении session limit и строит из них измеренный потолок. Если таких сообщений нет, конкретное время можно задать вручную параметром --hit, а результат сохранится в ~/.agentburn/ceiling.json.

Codex CLI записывает собственный rate_limits.used_percent рядом с каждым запросом. agentburn сопоставляет эти значения с локальным взвешенным расходом и оценивает потолок по медиане. При этом инструмент учитывает ограничение: процент провайдера относится ко всем устройствам и приложениям аккаунта, тогда как локальные журналы Codex содержат только часть потребления.

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

Сколько стоит длинный контекст

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

agentburn context измеряет реальный размер контекста в вызовах Claude Code и группирует расход по диапазонам. Команда также считает две практические метрики:

1. Сколько окна не было бы израсходовано, если бы сессия перезапускалась после достижения выбранного порога через /clear.
2. Сколько контекста добавляют отдельные вызовы Skill, усредняя изменение размера контекста после загрузки навыка.

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

Отчёты о деньгах и источниках расхода

Когда агент работает через API с оплатой по токенам, основной вопрос меняется: не «когда закончится окно», а «куда ушли деньги». Основной отчёт agentburn показывает расход по категориям источников:

• cron;
• subagent;
• шлюзы для Telegram, Discord и WhatsApp;
• интерактивный cli.

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

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

Команда why ищет не только категории, но и поведение: повторные чтения, шторм повторных попыток, простаивающие heartbeat-задачи, расход каждой cron-задачи и хаотичное расширение контекста.

Расход отдельных коммитов

agentburn commits связывает сессии агентов с историей Git. Он сопоставляет рабочий каталог и ветку с моментами появления коммитов, а затем считает объём usage между двумя соседними коммитами. Такой отчёт отвечает на вопрос не «сколько стоил месяц», а «во что обошлась конкретная функция или исправление».

Результаты можно сгруппировать по репозиторию. Для локального анализа команда читает git log в режиме read-only и ничего не изменяет в репозитории.

Рекомендации без автоматического применения

agentburn fix превращает найденные причины в готовые изменения конфигурации. Генераторы патчей существуют только для рычагов, подтверждённых исходным кодом или документацией соответствующего агента.

Для Claude Code утилита может предложить:

• удалить зарегистрированные, но ни разу не вызванные MCP-серверы;
• сократить всегда загружаемые файлы памяти;
• задать измеренный порог перезапуска сессии;
• убрать тяжёлые навыки из регулярной загрузки.

Для Hermes доступны настройки модели и наборов инструментов для cron-задач и платформ. Для OpenClaw — параметры heartbeat, включая период, активные часы, модель и облегчённый контекст.

Команда не применяет изменения автоматически. Это сделано намеренно: конфигурация агента остаётся под контролем пользователя. Можно вручную внести предложенный патч, сохранить исходную скорость расхода через --save-baseline, а затем сравнить результат командой --compare.

Поддерживаемые агенты

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

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

Обычный анализ полностью локальный: agentburn читает журналы без изменений, не использует аккаунты, телеметрию и сетевые вызовы. Локальный кэш разбора хранится в ~/.agentburn/cache с правами доступа 0700. В нём остаются только имена инструментов и усечённые ключи аргументов, но не содержимое сообщений.

Журналы transcript обычно только дописываются. Благодаря этому каждый файл разбирается один раз, а результат кэшируется по размеру и времени изменения. В примере проекта 30 дней логов Claude Code объёмом 3,1 ГБ разбираются около 190 секунд; последующие запуски занимают примерно 3 секунды, а размер кэша составляет около 29 МБ. Изменившийся файл разбирается повторно.

Сетевые команды отдельно обозначены: drift загружает публичные данные трендов, а --submit только открывает заранее заполненную форму GitHub Issue, которую пользователь должен проверить и отправить. Полностью офлайн-альтернатива доступна через --trends FILE.

MCP и готовый навык

Проект также предоставляет локальный MCP-сервер с командами burn_report, burn_limits, burn_context, burn_commits, burn_why и burn_card. Через него агент может проанализировать собственные журналы и объяснить расход. Для Claude Code сервер регистрируется так:

claude mcp add agentburn -- agentburn mcp

Для пользователей, предпочитающих навыки, в репозитории есть готовый SKILL.md для Claude Code и эквиваленты для Hermes и OpenClaw. Однако основным продуктом остаётся локальный профилировщик, а не агент, который сам пишет код.

Итоги

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