sessionlint

ccusage shows the bill. sessionlint shows patterns behind it — and helps agent loops land.

sessionlint reads your local Claude Code session history and identifies patterns that often drive API-equivalent cost. It reports honest ranges with labeled assumptions rather than pretending every heuristic is causal, then helps future sessions avoid repeated waste.

Three layers, all in one CLI:

• Audit — a read-only linter over your existing transcripts, with a replay-verified --verify mode.
• Live session — a statusline burn gauge, per-session budgets, and cheaper-model delegation for subagents.
• Autonomous runs — budgets, a convergence watchdog, and morning-after reports for Ralph/GSD-style loops, headless runs, and CI.

Install

Requires Bun:

curl -fsSL https://bun.com/install | bash   # if you don't have Bun
bunx sessionlint                            # that's the whole setup

No config, no account, no server. It reads Claude Code's transcripts from your own disk — ~/.claude/projects, or $CLAUDE_CONFIG_DIR/projects if you use a custom config dir (it even detects the case where Claude Code misplaced them).

What a report looks like

Excerpt of real output, run against this repo's synthetic test fixtures:

$ sessionlint

sessionlint · 2 sessions analyzed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  session  syntheti  2 turns
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ CACHE-NUKE             turns 1–2                -$0.03–$0.01
    Model switch claude-opus-4-8 -> claude-sonnet-5 was followed by
    ~8,500 tokens billed as fresh input. The switch occurred within the
    default five-minute cache TTL; the cost range spans both cache-hit
    and cache-cold counterfactuals.
    → sessionlint explain cache-nuke

  session cost: $0.04 API-equivalent · could plausibly have been ~$0.03–$0.04

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  session  syntheti  5 turns
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠ MISSING-CLEAR-AT-TOPIC-BOUNDARY turns 1–5                $0.19–$2.19
    Context grew to ~802,000 tokens and was never cleared or compacted
    for the rest of the session — consider /clear or /compact at a
    natural topic boundary.
    → sessionlint explain missing-clear-at-topic-boundary

  session cost: $2.71 API-equivalent · could plausibly have been ~$0.52–$2.52

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  2 findings across 2 flagged sessions · replay-audit with: sessionlint --verify
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Every finding names its rule, shows the evidence, and gives a $ range with labeled assumptions. Findings are always suppressible (--suppress <rule-id>) — sessionlint tells you what happened; it never overrules you.

Commands

| Command | What it does | |---|---| | sessionlint | Lint your history; findings with $ ranges. --json / --md, --dir <path> to point elsewhere | | sessionlint --ci | CI gate: versioned JSON to stdout, non-zero exit when a finding meets --fail-on <error\|warning\|info> (default error) | | sessionlint sessions | List sessions: id, date, turns, API-equivalent cost estimate | | sessionlint explain [<rule>] | What a rule detects, why it costs, how to fix it | | sessionlint doctor | Environment check: where sessions are read from, how many found, pricing freshness | | sessionlint export --redact | Write redacted copies of your sessions (prose/paths/secrets removed) so you can share history. --out <dir> | | sessionlint --verify | Replay-audit findings with real, billed API calls — cost preview + confirmation first | | sessionlint statusline | Burn gauge for Claude Code's statusLine.command | | sessionlint budget set <usd> | Per-session $ budget for the statusline sentinel (status / off) | | sessionlint auto-delegate <model> | Route subagents to a cheaper model from the next session | | sessionlint watch | Supervise an in-session loop (ralph-loop, GSD) by tailing transcripts — read-only unless you opt in | | sessionlint loop -- <cmd> | Wrap an external loop with budgets + convergence watchdog | | sessionlint run --prompt <text> | Budgeted, model-laddered headless claude -p run | | sessionlint report | Morning-after summary of the last loop run | | sessionlint help | Full flag reference |

The rules

| Rule | What it catches | |---|---| | cache-nuke | Fresh-input processing after a model switch, with TTL-aware attribution and dynamic severity | | late-compaction | Context filled up until auto-compaction hit, after carrying the excess for many turns | | giant-file-read | A single read pulling 1,000+ lines into context (offset-limited reads of big files don't count) | | missing-clear-at-topic-boundary | Context grew huge and never got a /clear or /compact | | repeated-identical-prompt | The same prompt retried verbatim — the first attempt's cost bought nothing |

Details per rule: sessionlint explain <rule> or docs/rules/.

Privacy & honesty

• Local-only. Your transcripts never leave your machine. No server, no account, no telemetry.
• Read-only by default. Anything that spends money (--verify, run) shows a cost preview and requires explicit confirmation. --paranoid blocks SessionLint-owned API and webhook calls; it cannot sandbox commands you explicitly launch.
• Ranges, not points. Dollar math runs against a pinned, dated pricing table with a staleness warning (sessionlint doctor shows its age). Anything not measured exactly is a labeled assumption.

Status

Young but real: dogfooded on the author's own history, with a published test suite. The first replay-verified equivalence audit was inconclusive (0/5 sampled turns matched on a cheaper model, far too small a sample for a general conclusion) and is published as-is because honest uncertainty is the point.

Contributing your history to the validation study

The rules are still heuristics until their precision is measured on real, diverse sessions. If you'd like to help, you can donate a redacted copy of your history:

sessionlint export --redact --dry-run   # preview: shows exactly what would be shared, writes nothing
sessionlint export --redact             # writes redacted session-NNN.jsonl + a MANIFEST.md receipt

The export removes prose, file contents, paths, filenames, secrets, and free-text keys, and keeps only what the rules need (model names, timestamps, usage token counts). It writes a MANIFEST.md receipt describing exactly what's included, and a self-check flags any residual secret/email pattern. sessionlint never transmits anything — you review the folder and share it privately yourself. Redaction is best-effort; please open a couple of files and confirm you're comfortable before sending.

Development

bun install
bun test

MIT © Preyash Yadav