session-health

Session Health Check

Show the user real session health data — not estimates. Parse actual token counts from the JSONL transcript.

How to Get Real Data

For current session only:

python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py" --current

For all sessions:

python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py"

For a specific project:

python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py" "project-name-fragment"

When invoked directly (not via time-menu), ask the user first with AskUserQuestion: Question: "Which sessions?" Header: "Health" Options:

1. Label: "Current Session" Description: "Just this session"
2. Label: "All Sessions" Description: "All active projects"

To override the compaction threshold (default 1M):

python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py" --threshold 800000

Combined:

python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py" --threshold 800000 "project-name-fragment"

For structured output (programmatic consumption — preferred when you need to extract specific fields rather than display them):

python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py" --format json --current

Run python "${CLAUDE_PLUGIN_ROOT}/scripts/session_health.py" --help for the full flag and exit-code reference.

The script parses JSONL transcripts and reads actual usage blocks from API responses to get:

• Real context usage — input_tokens + cache_read_input_tokens + cache_creation_input_tokens from the last assistant turn = actual context window size
• JSONL file size — total transcript weight
• Compaction count — how many compact_boundary markers exist
• Turn count — total assistant responses
• Cache efficiency — cache read vs write tokens
• Total tokens — cumulative input and output across the session

How Context Is Calculated

The JSONL contains usage data on every assistant message:

"usage": {
  "input_tokens": 42,
  "output_tokens": 1500,
  "cache_read_input_tokens": 450000,
  "cache_creation_input_tokens": 2000
}