
Session Bloat Watch — Find Oversized Sessions
Every Claude Code turn re-reads the whole conversation, so long sessions cost more with each turn. This read-only report ranks your local sessions by size, turns, images and cache-read tokens, shows the average re-read per turn, and flags the ones worth restarting. Metadata only (never prints message text), --json and --fail-on-warn for cron. Python 3 only; no network calls or credentials.
#Ingénierie
Note
Davantage d’évaluations nécessaires
Vendus
0
Mode d’utilisation
Télécharger
The problem
Each turn of a Claude Code session re-reads the whole conversation from the prompt cache. The longer a session runs, the more every later turn re-reads. Two or three long-lived sessions can account for most of your usage, and nothing in the terminal tells you which ones.
What it does
scripts/session_bloat_watch.py reads the session logs Claude Code keeps on disk (~/.claude/projects/<project>/<session>.jsonl) and prints one row per session, largest cache-read first:
session size turns imgs cache_read per_turn modified flags
a1b2c3d4 105.9MB 4822 74 1.2G 248.7k 2026-11-09 12:46 size>=8MB,images>=40,cache_read>=500M,reread/turn>=150k
size- file size on diskturns- assistant messages (counted once per message id; the log repeats ids per content block)imgs- image blocks, including images inside tool resultscache_read- total cache-read input tokens;per_turn- average re-read each turnflags- thresholds crossed (defaults: 8 MB, 40 images, 500M cache-read, 150k re-read per turn)
It reads metadata only. It never prints message text, never writes, and never deletes.
What you get
scripts/session_bloat_watch.py- the report (table or--json),--since-hours,--top, thresholds, and--fail-on-warn(exit code 10) for cron or a hook.tests/test_package.py- 12 tests on synthetic logs: duplicate ids, nested images, malformed lines, sorting and flags, exit codes, time filter, no message text in output, missing root.SKILL.md- instructions for Claude Code (report, recommend a restart, never delete).LICENSE- purchaser license.
Quick start
python3 scripts/session_bloat_watch.py --since-hours 24 --top 10
python3 scripts/session_bloat_watch.py --json --fail-on-warn # for a scheduled check
python3 scripts/session_bloat_watch.py --root /path/to/projects # non-default location
Limits
- It relies on the current JSONL layout (
message.usage.cache_read_input_tokens,message.id,imageblocks). If a future version changes the layout, counts can read 0; the tests show the layout expected. - Token numbers come from the logs and describe usage, not your bill or plan limits.
- A session that is big but finished costs nothing more; use
--since-hoursto look at live ones. - Python 3.8+. Standard library only. No network calls, no installers, no background services, no credentials.


