Session health

Skill AfterRealm/father-time/skills/session-health

Check your current session's health — real context usage from JSONL token data, compaction proximity, session weight, and rate limit status. Use when asking about session size, compaction, context window, rate limits, "how big is my session", "how close to compaction", or "should I checkpoint".From its SKILL.md

Install

npx -y skills add AfterRealm/father-time --skill session-health

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

5 stars5 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.7 KB, as published. Nobody here has run it

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:

Label: "Current Session" Description: "Just this session"
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
}

Real context size = input_tokens + cache_read + cache_creation from the last turn. This is the actual number of tokens sent to the API, which equals the current context window usage.

Context window size depends on the model variant:

claude-opus-4-7, claude-opus-4-6, claude-sonnet-4-6: 200K tokens (default)
claude-opus-4-7[1m], claude-opus-4-6[1m], claude-sonnet-4-6[1m]: 1M tokens (explicit 1M-context variant)

The script defaults to a 1M threshold but compaction may trigger earlier depending on the user's settings. Pass --threshold with their actual context window size if you know it.

context_pct = real_context / threshold × 100
Default threshold: 1,000,000 tokens
Users can specify their compaction threshold via --threshold

No guessing. No heuristics. Real numbers from the API.

Compaction Threshold

Different users have different compaction thresholds. If the user tells you their compaction threshold (e.g., "my compaction is at 800K"), pass it via the --threshold flag. If they don't specify, use the default (1M).

Ask the user for their threshold if the percentages seem off or if they mention their numbers don't match.

Compaction Risk

Context %	Risk	Action
< 30%	Low	All clear
30-60%	Moderate	Healthy, keep going
60-80%	High	Consider checkpointing
80%+	Imminent	Checkpoint NOW, compaction incoming

Response Format

Present ALL data from the script output in a table. Include every field — do not omit anything:

Project	JSONL	Context	Risk	Compactions	Turns	Cache	Tokens

Then show rate limits below the table if available. Follow with recommendations if anything needs attention.

When to Warn

Context > 70%: "Checkpoint your progress — compaction is approaching."
Context > 85%: "Compaction is imminent. Checkpoint NOW."
0 compactions + high context: "First compaction hasn't happened yet — after it fires, older context will be summarized."
Multiple compactions: "This session has compacted [N] times. Context is being managed but consider starting fresh for complex new work."
Everything healthy: "Session looks good. Carry on."