Session Report

Generates a single self-contained HTML file that reconstructs an agent session from its transcript and shows what is in the model's context window and how every token is spent — a forensic debugger for context bloat and the "dumb zone" (context-rot past ~40% of the window).

This is a user-invoked command (

/session-report

); it is not auto-invoked by the model. The session id is passed as the

$session_id

argument.

What the report shows

Verdict header + gauge: peak context vs window, health (Healthy / Degrading / Rotting), one-click jump chips to every issue.
Context budget at peak: a stacked bar + table partitioning the peak context into system+tools, listings (skills/agents/tools), CLAUDE.md/memory, opened files, user prompts, tool results, assistant text, thinking, and an honest "unattributed (tool schemas/overhead)".
Context-growth timeline: inline-SVG stacked area of real context size per turn, with the dumb-zone band, the 200K-model ghost line, compaction cliffs, peak marker, and the first dumb-zone crossing.
Loaded artifacts: CLAUDE.md/AGENTS.md/memory sizes (read from disk), skill/agent/tool listings, opened files — sortable, with "trim me" callouts.
Biggest items and a full collapsible history of every event (tool calls, results, attachments) with search/filter and the dumb-zone divider inline.

How to run

The generator is a zero-dependency TypeScript script with no build step. Run it from the skill's

scripts/

dir with the requested session id (

$session_id

). Pick whichever runtime the user has — they need only one:

bash

# Node >= 22.18 / >= 23.6 (native TS type-stripping; most Claude Code users have Node):
node generate-report.ts "$session_id" --open
# Bun:
bun run generate-report.ts "$session_id" --open
# Older Node (no type-stripping) — no install needed, npx fetches it:
npx tsx generate-report.ts "$session_id" --open

Detect what's available (e.g.

command -v node bun

) and use that. A direct transcript path and options also work, e.g.

node generate-report.ts /path/to/<id>.jsonl --out report.html --window 1000000

$session_id

is empty (the user ran

/session-report

with no argument), list recent Claude Code sessions and ask which one — e.g.

ls -t ~/.claude/projects/*/*.jsonl | head

— then re-run with the chosen id.

It finds the transcript by id under

~/.claude/projects/*/

, parses it, reads the relevant CLAUDE.md/AGENTS.md/memory files from disk, and writes the HTML (then

--open

s it if asked).Print the output path to the user.

Options:

```
--out <file>
```
— output path (default
```
./ccx-<id>.html
```
).
```
--window <tokens>
```
— context-window size. Leave the default. Claude Code always runs the 1M window, so keep 1M and do NOT pass
--window 200000
unless the user explicitly asks for a 200K view. A peak near 200K is normal 1M usage (~20% full), not evidence of a 200K cap — never infer the window from the peak or from a healthy-looking gauge, and never regenerate to "double-check." If the user does want to compare, the report header has a live in-browser window override, so there's no need to regenerate at all. (Codex records its real window directly, so this flag is irrelevant there.)
```
--dumb-zone <frac>
```
— degradation threshold as a fraction of the window (default
```
0.40
```
).
```
--no-subagents
```
— skip parsing subagent transcripts.
```
--no-redact
```
— disable secret redaction. Best-effort secret redaction (API keys, tokens, private keys, credential assignments) is ON by default; this flag turns it off and embeds the transcript verbatim.
```
--codex
```
— force Codex-rollout parsing (auto-detected by default from the file/path).

Key concepts (so you can interpret the report for the user)

Ground truth vs estimate: per-turn context size is exact from
```
usage
```
metadata(
```
input + cache_read + cache_creation
```
); per-item sizes are chars/4 estimates.
Thinking is the usual hidden giant: thinking text is not stored in the transcript, but it is retained in context. The report recovers it from real
```
output_tokens
```
minus visible text/tool_use — so a huge "thinking" band is accurate, not a guess.
System+tools residual: first-turn context minus visible loads = the fixed floor (system prompt + tool schemas + global CLAUDE.md). Not in the transcript; partly attributed from disk.
Unattributed = real peak minus everything attributable ≈ growing tool-definition schemas (from tool search / many MCP servers), per-turn reminders, and encoding overhead. Large value ⇒ tool bloat.

Codex sessions

Codex rollouts (

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl

) are also supported; Codex even records

model_context_window

directly. Pass the rollout path. See

scripts/lib/codex.ts

Notes

Output is a single HTML file — no server, no network, no external libraries. Open in any browser.
A deterministic script reads the transcript and writes the HTML; the model never reads or echoes session content. CLAUDE.md/AGENTS.md/memory files are read for size only and are not embedded. The report is a local, private, human-facing artifact — it is not meant to be fed back into an LLM as context.
Transcript content is HTML-escaped (safe to open in a browser — no XSS), and best-effort secret redaction runs by default, but the file may still contain sensitive data from your session — review before sharing. The report opens with a dismissible banner reminding you of this; use
```
--no-redact
```
to embed the raw transcript verbatim.
Large sessions produce multi-MB files (everything is inlined and collapsed by default).

session-report

NPX Install

Tags

SKILL.md Content