Codex Insights (Offline)

Generate a full local report from Codex session logs, including:

• report.json (raw aggregate data)
• report.base.html (base dashboard shell)
• insights.html (detailed Chinese insights snippet)
• report.html (final report with insights injected)

Quick Start

1. Generate report data and final HTML (default: last 30 days).

python3 scripts/codex_insights.py --days 30

Force-refresh narrative sections (ignore TTL cache):

python3 scripts/codex_insights.py --days 30 --force

If your environment blocks writes to ~/.codex/tmp, use:

python3 scripts/codex_insights.py --days 30 --out-dir /tmp/codex-insights-out --cache-dir /tmp/codex-insights-cache

Outputs (defaults):

• ~/.codex/tmp/codex-insights/report.json
• ~/.codex/tmp/codex-insights/report.base.html
• ~/.codex/tmp/codex-insights/insights.html
• ~/.codex/tmp/codex-insights/report.html

Open ~/.codex/tmp/codex-insights/report.html locally.

2. (Optional) If you want to provide custom insight text manually, override:

python3 scripts/inject_insights.py \
  --base ~/.codex/tmp/codex-insights/report.base.html \
  --insights ~/.codex/tmp/codex-insights/insights.html \
  --out ~/.codex/tmp/codex-insights/report.html

Common Options

• Time range:
  • --days 7
  • --since 2026-01-01 --until 2026-02-11
• Locations:
  • --sessions-dir ~/.codex/sessions
  • --out-dir ~/.codex/tmp/codex-insights
  • --cache-dir ~/.codex/usage-data/codex-insights
• Privacy:
  • --redact off (default is on)
  • --include-excerpts on (default is off)
• Qualitative facets (Claude-like outcome/friction tags; optional, uses codex exec):
  • --facets-provider codex
  • --facets-max-new-sessions -1 (default: all per run; cached)
  • --facets-selection high-signal (default; picks sessions that are most likely to generate useful facets)
  • --facets-model gpt-5.2-codex (optional)
• LLM global narrative (optional, uses codex exec and cached output):
  • --insights-provider codex
  • --insights-model gpt-5.2-codex (optional)
• Narrative cache:
  • --narrative-ttl-seconds 3600 (default 1 hour)
  • --force / --force-narrative to bypass narrative cache

Troubleshooting

• Report is empty: increase time range (--days 90) and confirm sessions exist under ~/.codex/sessions/.
• Missing token stats: some sessions may not have token_count events; the report will note this in report.json["notes"].
• Parse errors: rerun with --debug and check ~/.codex/usage-data/codex-insights/index.json for the failing file.

References

• references/report_schema.md: what report.json contains.
• references/insights_prompt.md: exact format for the injected Global Insights snippet.