claude-session-diagnostics

Cost and prompt-cache diagnostics for Claude Code session transcripts. Python 3.11 or later, standard library only, no dependencies.

Claude Code records every session as a JSONL transcript below ~/.claude/projects. Each assistant record carries the token counts that the API reported: what was sent uncached, what was written to the prompt cache, and what was read back from it. csd reads those records and reports what they cost.

It answers three questions:

• How often must you use a session to keep its cache warm?
• What do you pay when the cache expires?
• Which sessions can you go back to now, and for how long? (csd warm)

The tool reads your transcripts only. It sends nothing anywhere, and it makes no API calls.

Install

There are no dependencies. Install the csd command from PyPI:

pip install claude-session-diagnostics
csd summary

Or run it from a copy of this repository:

git clone https://github.com/keziacousins/claude-session-diagnostics
cd claude-session-diagnostics
python -m csd summary

Use

csd warm             # lanes that are still warm, and the time they have left
csd summary          # totals, cache hit rate, cost of restarts
csd models           # requests by model and the rates applied
csd growth           # how cost accumulates as a session becomes longer
csd ttl              # evidence for how long the cache stays warm
csd decay            # measured cache decay against idle time
csd cold             # the most expensive cold starts, in order
csd startup          # startup cost, for all projects and for each one
csd projects         # cost, restarts and startup cost for each project
csd misses           # cache misses that the API reports, and their causes
csd subagents        # cost and shape of delegated work
csd coverage         # how complete the transcript record is
csd sessions         # cost of each session
csd trace SESSION    # request-by-request ledger for one session
csd crossover        # one long warm session against several short ones
csd export           # records for each session, as JSON

Every command accepts --root (transcript directory, default ~/.claude/projects), --project SUBSTRING, --project-depth N and --ttl MINUTES. Use csd <command> --help for the options of one command.

Start with csd summary for the totals, then csd cold to see which sessions cost the most to restart.

What is still warm

csd warm reports the sessions that you can go back to now. It gives the time that each cache has left, the project, the name of the session and its id, what the next request pays while the cache is warm, and what the same request pays after the cache expires. The session that you run the command in is marked.

csd warm                  # the lanes that are still warm
csd warm --window 300     # also the lanes that expired in the last 5 hours

This command reads only the transcripts that changed inside the window, and therefore it is fast.

Project labels

Project labels come from the cwd that each transcript records. The tool shows the last --project-depth parts of that path, and the default is 2, for example acme/acme-core.

The directory names below ~/.claude/projects replace each / with -, and that encoding cannot be decoded: the name -src-acme-acme-core agrees with acme/acme-core and equally with acme-acme/core. The recorded cwd is used instead. --project matches against the complete working directory.

Documentation

• FINDINGS.md — what one corpus of approximately 26,000 requests shows about cache lifetime, restart cost and session length. These are hypotheses from a single user's usage, not established facts. Each section names the command that reproduces it, so you can test the claims against your own transcripts. Disagreements are welcome.
• DESIGN.md — the terms, the cost model and every measurement decision, with the reason for each. Read this before you trust a number, or before you change the parser or the prices. Review of the method is more valuable than agreement with the numbers.

Contributing

Two kinds of contribution are especially useful:

1. Run it on your own corpus and report where your results differ from FINDINGS.md. Include the command and its output.
2. Review the method. If the parsing, the deduplication or the cost arithmetic is wrong, every number here is wrong with it.

python -m unittest discover -s tests

The suite has 115 tests and runs on Python 3.11 through 3.14. It uses synthetic fixtures, so it cannot catch a systematic pricing error — DESIGN.md explains how to cross-check cost changes against a frozen copy of a real corpus.

To report a security problem, follow SECURITY.md. Transcripts are private data, so remove anything you do not want to publish before you paste output into an issue.

Layout

csd/pricing.py    model price table, cache multipliers, cost arithmetic
csd/parser.py     JSONL discovery, deduplication, Request records
csd/session.py    sessions, warm segments, cold-start detection
csd/analysis.py   decay curve, restart accounting, strategy comparison
csd/cli.py        argparse CLI
tests/            unittest suite
DESIGN.md         terms, cost model and measurement decisions
FINDINGS.md       results from one corpus, framed as hypotheses

Prior art

ccusage is the reference for the cost calculation. This project follows its (requestId, message.id) deduplication. It adds the split between the 5-minute and 1-hour caches, the analysis of segments, and the accounting of restarts.

Attribution

Authored by Claude Opus 5. Prompted, reviewed and tested by Kezia Cousins.

Licence

MIT. See LICENSE.