In English. claude-code-spend counts the tokens your Claude Code sessions and Claude Agent SDK runs spend, with the prompt cache broken down: 5-minute writes, 1-hour writes, reads and the cache hit rate. It reads the JSONL session logs under ~/.claude/projects, or Agent SDK messages you pass from your code, merges the duplicate lines of one API call, and groups the calls by model, session or day. Cost is an estimate by a price table (USD per million tokens) that you can override with a JSON file. TypeScript, Node ≥ 22.18, zero runtime dependencies. For a broader, popular tool see ccusage; this one is narrower and focused on the cache split and on Agent SDK messages.
Учёт собственного расхода токенов Claude: сколько ушло на вход, на выход, на запись в кэш промпта и на чтение из него, и во сколько это обошлось бы по ценам API.
Источники два:
- Журналы сессий Claude Code — JSONL-файлы в
~/.claude/projects/**, вместе с журналами суб-агентов в подкаталогах сессий. - Сообщения Claude Agent SDK — объекты, которые ваш код получает из
query(). Тип SDK не нужен: нужные поля описаны своими типами.
Разрезы — по модели, по сессии, по дню. В каждой строке отчёта: вход, выход, запись кэша на 5 минут, запись на 1 час, чтение кэша, доля попаданий в кэш и оценка в долларах.
Каждый ход агента отправляет модели весь разговор заново: системный промпт, описания инструментов, историю, результаты инструментов. Кэш промпта позволяет не платить полную цену за начало запроса, которое не изменилось с прошлого раза.
- Запись в кэш дороже обычного входа: 1,25× на 5 минут, 2× на 1 час.
- Чтение из кэша — 0,1× цены входа, у части новых моделей ещё дешевле.
У агента префикс растёт с каждым ходом, а новое в запросе — только последний кусок. Поэтому основная масса входных токенов — это чтение из кэша, и стоимость сессии зависит прежде всего от того, какая доля промпта пришла из кэша. Пример на модели с входом $5 за миллион: 100 000 токенов промпта без кэша стоят $0,50, из кэша — $0,05. Если кэш теряется (пауза дольше его жизни, смена модели, правка начала промпта), следующий ход платит запись заново, 1,25× или 2×.
Поэтому отчёт показывает запись и чтение отдельно и считает долю попаданий:
доля попаданий = чтение / (вход + чтение + запись 5 мин + запись 1 ч)
Нужен Node ≥ 22.18: он запускает TypeScript сам, без сборки. Зависимостей во время работы нет.
git clone https://github.com/SHOTBOTik/claude-code-spend
cd claude-code-spend
node src/cli.ts # все журналы в ~/.claude/projects, по модели
node src/cli.ts --by day --since 2026-01-01
node src/cli.ts --by session --json > spend.jsonnode src/cli.ts [--dir <путь>] [--since YYYY-MM-DD] [--by model|session|day] [--json]
| Опция | Что делает |
|---|---|
--dir <путь> |
где искать журналы, по умолчанию ~/.claude/projects; *.jsonl ищутся во всех подкаталогах |
--since YYYY-MM-DD |
только вызовы этого дня и позже |
--by model|session|day |
разрез, по умолчанию model |
--json |
отчёт в JSON вместо таблицы |
--prices <файл> |
своя таблица цен поверх встроенной, см. «Цены» |
--unsplit 5m|1h |
куда относить запись в кэш, у которой нет разбивки на 5 мин и 1 ч; по умолчанию 5m |
--utc |
дни по UTC, а не по местному времени |
Битые строки (недописанная последняя строка, обрезанный файл) пропускаются и считаются в сводке. Код выхода: 0 — отчёт напечатан, 2 — ошибка в опциях или при чтении.
На синтетических журналах из трёх файлов: основная сессия на Opus, суб-агент на Haiku в подкаталоге сессии, вторая сессия на Sonnet, где кэш часто теряется. Одна строка нарочно оборвана.
$ node src/cli.ts
~/.claude/projects
3 files, 119 lines, 77 calls (duplicate lines merged: 40), bad lines skipped: 1
model calls input output write 5m write 1h cache read hit rate USD
------------------------- ----- ------ ------ -------- -------- ---------- -------- ----
claude-opus-4-7 40 240 14,000 0 53,100 1,368,900 96.2% 1.57
claude-sonnet-4-6 25 62,500 12,500 60,000 0 240,000 66.2% 0.67
claude-haiku-4-5-20251001 12 480 7,200 16,700 0 99,000 85.2% 0.07
------------------------- ----- ------ ------ -------- -------- ---------- -------- ----
TOTAL 77 63,220 33,700 76,700 53,100 1,707,900 89.8% 2.31
USD is an estimate by list prices checked 2026-10-26; check them at https://platform.claude.com/docs/en/about-claude/pricing$ node src/cli.ts --by day --utc
...
day calls input output write 5m write 1h cache read hit rate USD
---------- ----- ------ ------ -------- -------- ---------- -------- ----
2026-01-10 52 720 21,200 16,700 53,100 1,467,900 95.4% 1.63
2026-01-11 25 62,500 12,500 60,000 0 240,000 66.2% 0.67
---------- ----- ------ ------ -------- -------- ---------- -------- ----
TOTAL 77 63,220 33,700 76,700 53,100 1,707,900 89.8% 2.31- calls — запросы к модели. Claude Code пишет одно сообщение ассистента несколькими строками, по строке на блок ответа; они склеены в один вызов. Сколько строк склеено, видно в сводке сверху.
- input — вход, который не пришёл из кэша и не записан в него. У агента с живым кэшем он мал: десятки токенов на ход.
- write 5m / write 1h — запись в кэш на 5 минут и на час. Большая запись при малом чтении значит, что кэш не доживает до следующего запроса или префикс меняется.
- cache read — чтение из кэша: обычно самая большая колонка и главный источник экономии.
- hit rate — доля промпта из кэша. В примере у сессии на Sonnet 66%: каждый пятый ход писал кэш заново, а вход каждого хода в кэш не попадал. Промпт у неё вчетверо меньше, чем у сессии на Opus, а стоит она почти половину той.
- USD — оценка по таблице цен, а не счёт. Звёздочка (
1.23*) значит, что у части вызовов нет цены: их модель не нашлась в таблице, токены посчитаны, деньги нет. Модели без цены перечислены под таблицей.?— цены нет ни у одного вызова строки. - Строка под таблицей про запись без разбивки появляется, когда в данных нет полей
cache_creation.ephemeral_5m_input_tokens/ephemeral_1h_input_tokens(старые журналы). Такая запись отнесена к 5 минутам, а--unsplit 1hотносит её к часу.
--json даёт то же с точными числами: rows, total, unpricedModels и read — сводку чтения (files, lines, badLines, usageLines, duplicates, ignored).
Журналы Claude Code:
import { readLogs, summarize, formatTable } from './claude-code-spend/src/index.ts';
const { collector, stats } = await readLogs(); // ~/.claude/projects по умолчанию
const report = summarize(collector.calls(), { by: 'day', since: '2026-01-01' });
console.log(formatTable(report));
console.log(report.total.cacheHitRate, report.total.costUsd, stats.badLines);Сообщения Agent SDK — по одному, как они приходят из query():
import { query } from '@anthropic-ai/claude-agent-sdk';
import { Collector, summarize } from './claude-code-spend/src/index.ts';
const spend = new Collector();
for await (const m of query({ prompt: 'Разбери логи сборки' })) {
spend.feedSdkMessage(m);
// ...ваша обработка сообщения
}
const { total } = summarize(spend.calls(), { by: 'model' });
console.log(total.tokens, total.cacheHitRate, total.costUsd);Берутся сообщения type: 'assistant' (поля message.id, message.model, message.usage, session_id, parent_tool_use_id). Если включены частичные сообщения и кадр stream_event с message_delta несёт api_message_id, итоговый выход вызова берётся из него. Остальные сообщения пропускаются. Метод не бросает исключений на данных чужой формы.
Остальное API:
| Функция | Что делает |
|---|---|
new Collector({ unsplitWrite }) |
копит вызовы; feedLogLine(obj), feedSdkMessage(m, at?), calls(), stats |
summarize(calls, { by, prices, since, utc }) |
строки отчёта, итог и модели без цены |
callCost(tokens, price) |
доллары одного вызова |
findPrice(model, table) |
цена модели: суффикс даты, [1m] и префикс провайдера не мешают |
loadPrices(file?), parsePriceTable(json) |
таблица цен из JSON поверх встроенной |
cacheHitRate(tokens) |
доля попаданий или null |
formatTable(report) |
таблица для терминала |
Встроенная таблица — цены Claude API (first-party, стандартный тариф, глобальный инференс) с официальной страницы цен Anthropic. Сверено 26.10.2026. Цены меняются: перед тем как опираться на доллары, проверьте страницу и при нужде поправьте таблицу.
Множители кэша от цены входа, как на странице: запись на 5 минут — 1,25×, на 1 час — 2×, чтение — 0,1×. Исключения на дату сверки: чтение у Opus 5.5 и Sonnet 5.5 — 0,05×, у Fable 5.1 и Mythos 5.1 — 0,025×; в таблице у них своя цена чтения. Haiku 5.5 дороже на вызовах, где промпт (вход, чтение и запись кэша вместе) больше 100 000 токенов; тариф выбирается по каждому вызову отдельно.
Своя таблица — JSON, USD за миллион токенов. Модель из файла заменяет встроенную запись целиком, остальные остаются. Цена кэша, которую не указали, выводится из input по множителям.
{
"claude-opus-4-7": { "input": 5, "output": 25 },
"my-proxy-model": { "input": 2, "output": 8, "cacheRead": 0.1 },
"claude-haiku-5-5": { "input": 0.1, "output": 0.5, "longPrompt": { "over": 100000, "input": 0.5, "output": 2.5 } }
}node src/cli.ts --prices my-prices.jsonМодель ищется по самому длинному совпадающему id. После id допускаются только дата (-20251001, @20251001) и версия провайдера (-v1:0). Поэтому неизвестная версия, например claude-opus-4-9, не получит цену соседней: она попадёт в список «без цены».
src/collect.ts—Collector. Читаетusageвызова, склеивает строки по ключу «id сообщения + id запроса» (message.id+requestId; у сообщений SDK — толькоmessage.id). Каждое поле берётся как максимум по строкам, а не сумма: строка — снимок вызова на момент записи. Запись в кэш делится на 5 мин и 1 ч поcache_creation; что разбивкой не названо, идёт по правилуunsplitWrite. Сообщения модели<synthetic>(их пишет сам CLI, модель не вызывалась) пропускаются.src/logs.ts— обход каталога и чтение JSONL. Строки делятся только по\n:readlineрежет ещё и по U+2028/U+2029, которые JSON разрешает внутри строки, и такие строки журнала стали бы битыми.src/prices.ts— таблица цен, множители, поиск модели, стоимость вызова.src/aggregate.ts— разрезы, итоги, доля попаданий. Стоимость считается по каждому вызову и складывается.src/format.ts,src/cli.ts— таблица и CLI.
ccusage — более полный и популярный инструмент (около 19 тыс. звёзд на 26.10.2026). Сравнение ниже — только по его README на ту же дату. Сам ccusage я не запускал.
| claude-code-spend | ccusage (по README) | |
|---|---|---|
| Отчёты | по модели, сессии, дню | дневные, недельные, месячные, по сессиям, по 5-часовым блокам; разбивка по моделям |
| Источники | журналы Claude Code, объекты Agent SDK из кода | журналы Claude Code и других агентских CLI (Codex, OpenCode, Amp, Gemini CLI и др.) |
| Запись и чтение кэша | отдельно, запись — на 5 мин и 1 ч | запись и чтение отдельно; о делении записи на 5 мин и 1 ч в README не сказано |
| Доля попаданий в кэш | да | в README не упоминается |
| Цены | своя таблица с официальной страницы, переопределение JSON-файлом | данные цен LiteLLM, переопределение в ccusage.json, офлайн-режим |
| JSON | --json |
--json |
| Библиотека | да, в том числе для сообщений Agent SDK | в README описан только CLI |
Если нужен общий учёт расхода по многим инструментам и периодам, берите ccusage. claude-code-spend полезен, если нужно увидеть, как работает кэш (запись 5 мин против 1 ч, доля чтения), или считать расход прямо в своём коде на Agent SDK.
- Доллары — оценка по прейскуранту API, не счёт. Не учтены: fast mode, US-only инференс (
inference_geo, 1,1×), скидка Batch API, оплата веб-поиска и веб-загрузки за запрос, цены Bedrock и Google Cloud. - Формат журналов Claude Code не документирован как стабильный. Код опирается на
type: "assistant",message.id,message.model,message.usage,requestId,sessionId,timestamp,isSidechain; если формат изменится, вызовы могут перестать находиться. - Вызов относится к сессии и дню, где его увидели первым. Возобновлённая сессия, скопировавшая историю в новый файл, не удвоит расход, но старые вызовы останутся за старой сессией.
- Если одну и ту же сессию подать и журналом, и сообщениями SDK, она посчитается дважды: у сообщений SDK нет
requestId, и ключи не совпадут. - Выход вызова — максимум по его строкам. Если журнал оборван раньше последней строки вызова, выход будет занижен.
- Запись без разбивки по времени жизни относится к одному ведру целиком (
--unsplit), на глаз её не разделить. - Вызовы без времени при
--sinceотбрасываются; в разрезе по дню они идут в строкуunknown.
npm install # только typescript и @types/node для проверки типов
npm test # node --test
npm run typecheck # tsc --noEmitВсе тесты на синтетических данных (test/fixtures.ts): склейка дублей, разрезы по модели, сессии и дню, доля попаданий, стоимость с множителями и особыми ценами чтения, тариф длинного промпта, битые строки, U+2028 внутри строки JSON, записи без полей 5m/1h, сообщения Agent SDK, CLI.
Вынесено из Пульта — моего интерфейса поверх Claude Code: там этот учёт показывает, сколько стоит каждая нить и как работает кэш.
Код писали агенты Claude Code по моей постановке; постановка, проверка и приёмка — мои.