Skip to content

About

Claude token spend from Claude Code logs and Agent SDK messages, prompt cache split: 5m/1h writes, reads, hit rate

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

claude-code-spend

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.

Источники два:

  1. Журналы сессий Claude Code — JSONL-файлы в ~/.claude/projects/**, вместе с журналами суб-агентов в подкаталогах сессий.
  2. Сообщения 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.json

CLI

node 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

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 по моей постановке; постановка, проверка и приёмка — мои.

Автор и лицензия

SHOTBOTik · MIT, см. LICENSE.

About

Claude token spend from Claude Code logs and Agent SDK messages, prompt cache split: 5m/1h writes, reads, hit rate

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages