{"id":51326740,"url":"https://github.com/avirtual/ctxburn","last_synced_at":"2026-07-01T19:02:08.136Z","repository":{"id":361275096,"uuid":"1253832743","full_name":"avirtual/ctxburn","owner":"avirtual","description":"Grade your Claude Code sessions on token cost. Reads JSONL transcripts; no deps.","archived":false,"fork":false,"pushed_at":"2026-05-29T23:12:00.000Z","size":14,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T23:14:23.553Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avirtual.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T21:27:39.000Z","updated_at":"2026-05-29T23:12:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/avirtual/ctxburn","commit_stats":null,"previous_names":["avirtual/ctxburn"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/avirtual/ctxburn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avirtual%2Fctxburn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avirtual%2Fctxburn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avirtual%2Fctxburn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avirtual%2Fctxburn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avirtual","download_url":"https://codeload.github.com/avirtual/ctxburn/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avirtual%2Fctxburn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35019037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T19:02:04.259Z","updated_at":"2026-07-01T19:02:08.128Z","avatar_url":"https://github.com/avirtual.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ctxburn\n\n**Grade your Claude Code sessions on token cost.** Point it at your transcripts; it tells you which sessions burned money, why, and what to do about it.\n\nNo dependencies. No setup. It reads the JSONL transcripts Claude Code already writes to `~/.claude/projects`.\n\n```\n$ ctxburn\n========================================================================\nSESSION GRADER — 18 sessions · 1122M replay tokens · $4,300 total\ngrades: A:1  B:1  C:3  D:1  F:12\ngrade = last-10-turn avg context (absolute tokens/turn = cost).\n========================================================================\n\n  [F]  ca65462f  (aws-eks-infra)  $316\n       last-10 avg 488K · 542 turns · 0 compactions · 133.3M replay\n     FINDINGS:\n       - Cost: $315.83 on claude-opus — context replay+write $266 (84%),\n         output $49 (16%). (Output is 0.5% of tokens but 16% of cost.)\n       - Last-10-turn avg context: 488K re-sent every turn (the cost driver).\n       - Ran 542 turns without a single compaction.\n       - Largest dead weight: Read aws-eks-infra — 4.8M tokens (fetched 6x).\n     SUGGESTIONS:\n       \u003e Compact or /clear early and repeatedly.\n       \u003e Drop large one-shot outputs once consumed.\n       \u003e Pin or summarize frequently-needed files instead of re-reading.\n```\n\n## Why\n\nThe bill for an agentic coding session is **~96% context replay and \u003c1% generated output.** Every turn re-sends the entire accumulated context. So:\n\n\u003e **cost ≈ (context carried per turn) × (number of turns)** — the area under the context-growth curve.\n\nA long session that never compacts is a triangle: each late turn drags the whole history. Turn 500 can cost 30× turn 1. The lever that matters is **context discipline** — compact or `/clear` early and often. Plugins that shave tool output or tune caching are optimizing the rounding error; ctxburn measures the thing that actually moves the bill.\n\n## Install\n\nNot on PyPI yet — install from source:\n\n```bash\ngit clone https://github.com/avirtual/ctxburn\ncd ctxburn\npipx install .          # gives you the `ctxburn` command on PATH\n# or for development:\npip install -e .\n# or run it without installing:\npython3 -m ctxburn.cli --help\n```\n\n## Usage\n\n```bash\nctxburn                        # grade the last 7 days under ~/.claude/projects\nctxburn /path/to/project       # a specific project folder\nctxburn --all                  # ignore the time window\nctxburn --since 30             # last 30 days\nctxburn --session 845a0984     # full report for one session id\nctxburn --top 10               # detail the 10 most-improvable sessions\nctxburn --window 1000000       # context window for the ceiling-risk flag\nctxburn --by-project           # roll cost/grades up by project, with restart boot-floor\nctxburn --json                 # machine-readable output\n```\n\nBy default it focuses on the sessions worth improving (grade C/D/F) and collapses the efficient ones to a one-liner.\n\n`--by-project` rolls the per-session view up by project (cwd): one row per project with its boot count (= sessions, each a cold context load), worst/avg grade, total replay, and **boot-floor** — the one-time cache *write* a restart re-pays on each cold boot, summed across boots. It's the cross-session lens: a restart-heavy agent's bill is `boots × (boot-floor + the read-replay tail each session then grows)`, which no single-session view shows. Per-session detail also now prints a **\"where to cut\"** line — the turn index where context first crossed each grade band, i.e. where a `/clear` would have capped the tail.\n\n## Cold-cache misses (the \"walked away and came back\" tax)\n\nThe prompt cache has a **5-minute TTL**. If you step away mid-session and return after more than 5 minutes, the cache has expired — the next turn re-sends your *entire* context as a cache **write** (~12.5× the read rate) instead of a cheap read. ctxburn flags these: a turn with near-zero cache-read but a large cache-write (\u003e50K tokens), preceded by a \u003e5-minute idle gap. It reports how many happened, the longest idle gap, the cost, and the avoidable portion (write-rate minus read-rate). Two real ~190-turn Opus sessions doing near-identical work cost $30 vs $49 — **$10.33 of the gap was nothing but cold re-writes from leaving the session open across idle gaps** (one 6.5-hour gap). The fix is free: finish in focused sittings, or `/clear` before you step away — a small fresh context is cheaper to rebuild than a large one is to cold-re-write. This is a cost-leak flag, not a grade input (the grade stays your last-10 context height).\n\n## How the grade works\n\nThe grade is the **last-10-turn average context** — the tokens you were re-sending every turn by the end of the session. This is absolute (tokens = dollars), **not** normalized by window: replaying 200K tokens costs the same whether your window is 200K or 1M, so window size doesn't change your grade. It's used only for a secondary \"you're near the ceiling\" risk flag.\n\n| grade | last-10 avg context | meaning |\n|-------|---------------------|---------|\n| A | \u003c 40K  | lean — system + a few files + recent history |\n| B | \u003c 80K  | healthy |\n| C | \u003c 130K | getting heavy |\n| D | \u003c 180K | should have compacted a while ago |\n| F | ≥ 180K | re-sending a near-full window every turn |\n\nModifiers: a 150+ turn session with no compaction drops a grade; a session that compacted and ended lean earns one back.\n\n## Cost\n\nctxburn prices all four token tiers (uncached input, output, cache-write, cache-read) per model, matched on the `model` field in the transcript. **These are public list prices** (`opus` / `sonnet` / `haiku`) — enterprise contracts differ, so edit `PRICING` in `cli.py` to match your actual rates.\n\nA note the dollars make obvious: output is ~0.5% of *tokens* but ~16% of *cost* on Opus, because output is priced ~50× cache-read. Context replay still dominates, but output isn't free.\n\n## Caveats\n\n- Tool-result sizes (for the \"dead weight\" finding) are estimated from content length (~chars/4); the dead-weight/stale-carry figure is directional, shown as \"where to look,\" not a hard claim.\n- \"Used until\" for stale-carry uses file/command recurrence as a proxy.\n- The grade and cost (from token counts and pricing) are exact; the diagnostic offenders are heuristic.\n\n## License\n\nMIT © Bogdan Ionescu\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favirtual%2Fctxburn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favirtual%2Fctxburn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favirtual%2Fctxburn/lists"}