codex-session-insights

Generate a report analyzing your Codex sessions.

codex-session-insights reads your local Codex history, extracts recurring patterns from your sessions, and renders a narrative report as both HTML and JSON.

Quick Start

Run it directly:

npx codex-session-insights

The default flow is:

1. Read your local Codex thread index
2. Estimate likely analysis token usage
3. Let you confirm the plan in an interactive terminal
4. Generate report.html and report.json
5. Try to open the HTML report in your browser

If you only want the estimate first:

npx codex-session-insights --estimate-only

If you already know what you want and do not want the confirmation flow:

npx codex-session-insights --yes

What You Get

By default the tool writes:

• ~/.codex/usage-data/report.html
• ~/.codex/usage-data/report.json

The HTML report includes these sections:

• At a Glance
• What You Work On
• How You Use Codex
• Impressive Things You Did
• Where Things Go Wrong
• Open Loops (sessions that ended without confirmed completion)
• Features to Try
• On the Horizon
• One More Thing

How the headline numbers are defined

• Active Time sums the gaps between consecutive rollout events, skipping any gap longer than 30 minutes. The raw first-to-last span of each thread is shown separately as Thread span (wall clock) in the appendix.
• Median Turn is the time from a user message to the assistant's final answer for that turn. It includes tool, build, and sub-agent run time, so it describes how long turns take, not how responsive the model is.
• Tool Errors counts non-zero command exits plus failed tool calls. Probe misses such as rg, grep, or test exiting 1 with nothing found are excluded and reported separately.
• Failure Hotspots (by command) groups failures by the program that actually ran (git push, cmake, npm test), not by the Codex parsed_cmd type, which labels most compound commands unknown.
• Failure Causes is a heuristic classification from exit code and output text (test_failed, build_failed, git_error, command_not_found, interrupted, and so on). unclassified means the cause could not be determined.
• Session Types and Outcomes only cover threads that received an LLM label. Each panel states its coverage (for example "12 of 124 labeled threads"), and the narrative sections are instructed not to extrapolate beyond it. Re-running the tool extends coverage because labels are cached.

Typical Usage

Default run:

npx codex-session-insights

Lite local run for prompt and layout testing:

npx codex-session-insights --preset lite

Estimate first, then decide:

npx codex-session-insights --days 7 --limit 20 --facet-limit 8 --estimate-only

Use a custom output directory:

npx codex-session-insights --out-dir ./insights-output

Emit JSON to stdout instead of a terminal summary:

npx codex-session-insights --stdout-json

Include archived threads:

npx codex-session-insights --include-archived

Include sub-agent threads as well as main threads:

npx codex-session-insights --include-subagents

Choose the report language explicitly:

npx codex-session-insights --lang zh-CN
npx codex-session-insights --lang en

Use the OpenAI API instead of your local Codex CLI login: