session-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

生成单个自包含的 HTML 文件，根据 transcript 重建 Agent 会话，并展示 模型 context window 中包含的内容，以及每个 token 的消耗去向——这是一款用于诊断 context 膨胀和“dumb zone”（context 占用超过窗口约 40% 后出现的 context rot）的取证型调试器。

这是一个由用户调用的命令（

/session-report

）；模型不会自动调用它。session id 通过

$session_id

参数传入。

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.

判定摘要 + 仪表：峰值 context 与 window 上限对比、健康状态（Healthy / Degrading / Rotting），以及可一键跳转到每个问题的快捷按钮。
峰值时的 context 预算：堆叠条形图和表格，将峰值 context 拆分为 system+tools、清单（skills/agents/tools）、CLAUDE.md/memory、已打开的文件、用户提示词、工具结果、助手文本、thinking，以及如实标注的“未归因内容（工具 schemas/overhead）”。
Context 增长时间线：使用 inline-SVG 堆叠面积图展示每一轮的真实 context 大小，其中包含 dumb zone 区域、200K 模型的 ghost line、compaction 断崖、峰值标记，以及首次越过 dumb-zone 阈值的位置。
已加载的 artifacts：CLAUDE.md/AGENTS.md/memory 的大小（从磁盘读取）、skill/agent/tool 清单、已打开的文件——支持排序，并带有“建议裁剪（trim me）”提示。
最大项和完整可折叠历史记录，涵盖每个事件（工具调用、结果、附件），支持搜索/过滤，并在相应位置内嵌 dumb zone 分隔线。

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

undefined

生成器是一个零依赖、无需构建步骤的 TypeScript 脚本。请在 skill 的

scripts/

目录中使用请求的 session id 运行它。选择用户已有的任一 runtime 即可——只需具备其中一种：

bash

undefined

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`.

If `$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).

npx tsx generate-report.ts "$session_id" --open


检测可用的 runtime（例如 `command -v node bun`）并使用它。也可以直接传入 transcript 路径和选项，例如 `node generate-report.ts /path/to/<id>.jsonl --out report.html --window 1000000`。

如果 `$session_id` 为空（用户运行 `/session-report` 时未提供参数），则列出最近的 Claude Code 会话并让用户选择——例如 `ls -t ~/.claude/projects/*/*.jsonl | head`——然后使用选定的 id 重新运行。

它会在 `~/.claude/projects/*/` 下按 id 查找 transcript、解析内容、从磁盘读取相关 CLAUDE.md/AGENTS.md/memory 文件，并写出 HTML（如果指定 `--open`，随后打开它）。将输出路径告知用户。

选项：
- `--out <file>` — 输出路径（默认：`./ccx-<id>.html`）。
- `--window <tokens>` — context window 大小。**保持默认值。Claude Code 始终以 1M window 运行，因此应保留 1M，除非用户明确要求查看 200K 视图，否则不要传入 `--window 200000`。** 峰值接近 200K 是 1M window 下的正常用量（约占 20%），并不能证明存在 200K 上限——绝不能根据峰值或看起来健康的仪表推断 window，也绝不能为了“再次确认”而重新生成。如果用户确实想进行比较，报告标题提供了浏览器内实时 window 覆盖功能，因此完全不需要重新生成。（Codex 会直接记录其实际 window，因此该选项在那里无关。）
- `--dumb-zone <frac>` — 退化阈值，表示为 window 的一个小数比例（默认 `0.40`）。
- `--no-subagents` — 跳过解析 subagent transcripts。
- `--no-redact` — 关闭 secret redaction。默认开启尽力而为的 secret redaction（API keys、tokens、private keys、credential assignments）；此选项会将其关闭，并把 transcript 原样嵌入报告。
- `--codex` — 强制使用 Codex rollout 解析（默认根据文件/路径自动检测）。

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.

实测值与估算值：每轮 context 大小可通过
```
usage
```
元数据（
```
input + cache_read + cache_creation
```
）精确获得；单个项目的大小则按字符数/4估算。
Thinking 往往是最大的隐藏开销：thinking 文本不会存储在 transcript 中，但会保留在 context 中。报告通过真实的
```
output_tokens
```
减去可见文本/
```
tool_use
```
来恢复其大小——因此，巨大的“thinking”区间是准确值，而不是猜测。
System+tools 残差：首轮 context 减去可见加载项 = 固定基础占用（system prompt + tool schemas + global CLAUDE.md）。它不在 transcript 中；其中一部分可根据磁盘内容归因。
未归因内容 = 实际峰值减去所有可归因内容 ≈ 持续增长的工具定义 schemas（来自 tool search/大量 MCP servers）、每轮提醒和编码开销。数值很大 ⇒ 工具膨胀。

Codex sessions

Codex 会话

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

也支持 Codex rollouts（

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

）；Codex 还会直接记录

model_context_window

。传入 rollout 路径。请参阅

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).

输出为单个 HTML 文件——无需服务器、无需网络、无需外部库。可在任何浏览器中打开。
一个确定性脚本读取 transcript 并写出 HTML；模型绝不会读取或回显会话内容。CLAUDE.md/AGENTS.md/memory 文件仅读取大小，不会嵌入报告。该报告是一个本地、私密、面向人的产物——不应作为 context 回传给 LLM。
Transcript 内容会进行 HTML 转义（可安全地在浏览器中打开——不存在 XSS 风险），默认还会执行尽力而为的 secret redaction，但文件仍可能包含会话中的敏感数据——分享前请务必检查。报告打开时会显示一个可关闭的横幅，提醒用户注意这一点；使用
```
--no-redact
```
可将原始 transcript 原样嵌入。
大型会话会生成数 MB 的文件（所有内容均被内联，且默认折叠）。