开始使用
Session Bloat Watch — Find Oversized Sessions

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.
#工程
评分
需要更多评价
订单数
0
如何使用
下载

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 disk
  • turns - assistant messages (counted once per message id; the log repeats ids per content block)
  • imgs - image blocks, including images inside tool results
  • cache_read - total cache-read input tokens; per_turn - average re-read each turn
  • flags - 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, image blocks). 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-hours to look at live ones.
  • Python 3.8+. Standard library only. No network calls, no installers, no background services, no credentials.