Session Cost

---
name: session-cost
description: Посчитать токены (input/output/cache) сессии Claude Code по ее транскрипту - для сметы, отчета по задаче, сравнения генерации с перечитыванием контекста. Остаток лимита аккаунта не сюда, там `/usage`.
---

# session-cost

Считает токены сессии Claude Code по ее транскрипту, программно и без внешних API. `/usage` дает только % лимита аккаунта, `/cost` - ручной вызов; этот скилл дает сырые токены по типам, пригодные для сметы, отчета и автоматизации.

## Как работает

Claude Code пишет каждую сессию в `~/.claude/projects/<encoded-project>/<session-id>.jsonl`. У каждого assistant-сообщения есть `message.usage` с полями `input_tokens`, `output_tokens`, `cache_creation_input_tokens` (запись кэша), `cache_read_input_tokens` (чтение кэша). Скрипт считает только записи типа `assistant` с непустым usage. Повторные записи одного сообщения в транскрипте не завышают расход: учитывается последний непустой usage; сообщения без ID считаются отдельно.

Для каждого выбранного `<dir>/<id>.jsonl` добавляются `<dir>/<id>/subagents/*.jsonl`: при `--file`, `--session`, выборе текущей сессии и `--all-sessions`. Чужие сессии не включаются. Отсутствующий каталог субагентов дает нулевой вклад; ошибка доступа к существующему каталогу или файлу останавливает подсчет. Входные файлы не изменяются.

Текстовый вывод показывает основной контекст, суммарную строку субагентов (включая нулевую) и общий итог. В каждой группе есть число сообщений, четыре типа токенов, `work = output + cache_write` и `grand_total = input + output + cache_read + cache_write`.

В `--json` верхние поля `files`, `messages`, `tokens`, `work_tokens`, `grand_total` включают весь учтенный расход, в том числе субагентов. `files` перечисляет все прочитанные файлы без дублей. Группы `main` и `subagents` содержат те же пять полей. На верхнем уровне и в каждой группе есть `invalid_lines` и `messages_without_id`; общие числа равны сумме групп.

Непустой битый JSON пропускается с увеличением `invalid_lines`. Пустые строки и корректные служебные записи не считаются ни сообщениями, ни ошибками. `messages_without_id` показывает число учтенных записей без ID, для которых дедупликация невозможна. При ненулевых счетчиках stderr содержит причину, число записей и путь файла. Битый JSON дает код 3 с явно неполной сводкой, записи без ID - сводку с ограничением дедупликации. При успешном подсчете stdout с `--json` остается валидным JSON. Ошибки доступа и отсутствующий явно указанный файл дают код 1 и причину в stderr, без успешной частичной сводки в stdout.

Имя папки проекта - абсолютный путь рабочей папки, где каждый не-alnum символ заменен на `-` (`/Users/x/My.Proj` -> `-Users-x-My-Proj`).

## Запуск

```bash
python3 scripts/session-cost.py                 # текущая сессия (env CLAUDE_CODE_SESSION_ID), проект по CWD
python3 scripts/session-cost.py --session <id>  # конкретная сессия
python3 scripts/session-cost.py --file <path.jsonl>
python3 scripts/session-cost.py --project <dir> --all-sessions
python3 scripts/session-cost.py --json          # машиночитаемо
```

## Что знать про цифры (важно для честной сметы)

- **Текущая сессия** определяется по env `CLAUDE_CODE_SESSION_ID` (его ставит Claude Code) - надежно. Без него - свежайшая по mtime, а при **параллельных сессиях** в одном проекте это может оказаться ЧУЖАЯ сессия. Тогда указывай `--session` явно.
- **`cache_read` обычно доминирует** (десятки млн) - это перечитывание постоянного контекста (системный промпт, правила, память, схемы тулов) на каждом ходу, а НЕ работа по задаче. Показатель реального труда агента - **`output`** (и отчасти `cache_write`). Скрипт помечает это в выводе (строка `work`).
- **per-session = per-задача** только когда сессия однотемная. Для сессии, где смешаны разные задачи, точной разбивки по задачам нет - бери сессию целиком или дели вручную по границам.

## Когда НЕ применять

- Нужен остаток лимита аккаунта (не расход конкретной сессии) - это `/usage` или usage-эндпоинты аккаунта.
- Нужна стоимость в деньгах - скрипт дает токены; конверсию в валюту делать снаружи по актуальным ценам модели.