Codex Insight

Codex Insight

Generate a local-first Codex usage report similar in spirit to Claude Code /insights: a rich HTML report plus compact aggregate JSON, covering token totals, active sessions, workspace concentration, session cadence, interaction patterns, model mix, tool usage, quota snapshots, friction signals, context-pressure signals, copyable action items, and future workflow ideas.

Default Workflow

Use the full two-pass workflow by default when the user asks for /insight, /insights, or a Claude Code-style report. A complete report means the final HTML includes narrative insight JSON. Do not stop after the deterministic summary pass unless the user explicitly asks for a fast/offline/statistics-only run.

1. Run the bundled script from this skill directory to create only the factual

base and low-token narrative prompt: ``bash python3 ~/.codex/skills/codex-insight/scripts/codex_insight.py \ --days 30 \ --timezone Asia/Hong_Kong \ --language auto \ --summary-output reports/codex-insight-summary.json \ --insights-prompt-output reports/codex-insight-prompt.md \ --quiet ` If you are using a repo-local copy instead of the global install, run the same script from that copy's scripts/` directory.

1. Use a cheap/fast subagent or model for the mandatory narrative pass. Give it

reports/codex-insight-prompt.md and reports/codex-insight-summary.json only, then ask it to write JSON matching the schema in the prompt to: ``text reports/codex-insight-insights.json `` Do not load raw JSONL session logs into model context.

1. Re-run the script with the generated insight JSON:

``bash python3 ~/.codex/skills/codex-insight/scripts/codex_insight.py \ --days 30 \ --timezone Asia/Hong_Kong \ --language auto \ --html-output reports/codex-insight-latest.html \ --summary-output reports/codex-insight-summary.json \ --insights-input reports/codex-insight-insights.json \ --quiet ``

1. Treat the final HTML file as the primary report. Return a short summary and a path

to the HTML report instead of pasting the full report.

1. Add a short interpretation in the user's language when the report has a clear

pattern, such as one workspace dominating usage or context pressure being high. With --language auto, Chinese user-message history generates a Chinese report by default; use --language zh or --language en to force a language.

Options

• Change the time window with --days N.
• Use a different Codex home with --codex-home /path/to/.codex.
• Write the rich HTML artifact with --html-output /path/to/report.html.
• Optionally write a Markdown artifact with --output /path/to/report.md.
• Write compact aggregate JSON with --summary-output /path/to/summary.json.
• Write the second-pass narrative prompt with

--insights-prompt-output /path/to/prompt.md.

• Inject model-generated narrative sections with

--insights-input /path/to/insights.json.

• Choose report language with --language auto, --language zh, or

--language en.

• Use --compact to print/write a shorter report.
• Limit ranked table length with --top-n N.
• Use --quiet when writing artifacts so the full report does not flood the

current model context.

• Use --timezone local for the machine timezone, or pass any IANA timezone.

Fast / Offline Mode

Only use the deterministic one-pass fallback when the user explicitly asks for a fast, offline, or statistics-only run:

python3 ~/.codex/skills/codex-insight/scripts/codex_insight.py \
  --days 30 \
  --timezone Asia/Hong_Kong \
  --language auto \
  --html-output reports/codex-insight-latest.html \
  --summary-output reports/codex-insight-summary.json \
  --quiet

This fallback is useful for smoke tests, but it is not the default /insight experience.

Data Source

The script reads local Codex JSONL session logs under:

~/.codex/sessions/**/*.jsonl

It uses event_msg records where payload.type == "token_count" and sums info.last_token_usage inside the selected time window. This avoids double counting cumulative total_token_usage values.

Privacy and Safety

• Do not send session logs to external services.
• Do not print raw user prompts or assistant transcript text by default.
• Keep the report aggregate-only unless the user explicitly asks for examples.
• Prefer compact JSON for follow-up analysis; use a low-cost subagent/model for

narrative synthesis when one is needed.

• If no token_count records are found, say that the current Codex surface may

not emit local usage events and suggest widening the date range.

Report Shape

The primary output is a self-contained HTML report with:

• top metric cards
• At a glance / 概览
• project areas
• usage charts
• interaction style
• what works
• friction signals
• copyable actions
• future workflow opportunities
• a short memorable-pattern ending

The Markdown output remains available for terminal-first workflows and includes: At a glance, Executive summary, Project areas, Session cadence, Interaction patterns, Model mix, Usage trend, Workspace mix, Tool usage, Time of day, Client mix, Friction hotspots, Token-saving workflow, and Suggested follow-ups.

The compact JSON output is aggregate-only. It includes ranked workspaces, tools, models, interaction counters, and friction counters. It intentionally excludes raw prompts and assistant transcript text.

Narrative Insight JSON

The second-pass JSON can include:

• at_a_glance: what is working, what is hindering, quick wins, ambitious

workflows

• project_areas: interpreted project/workstream descriptions
• interaction_style: how the user tends to operate Codex
• what_works: impressive or compounding usage patterns
• friction: categories, descriptions, and aggregate examples
• recommendations: Codex instructions, features to try, and repeatable usage

patterns with copyable prompts

• on_the_horizon: higher-leverage future workflows
• memorable_moment: a short closing pattern

If the JSON is absent or incomplete, the HTML falls back to deterministic local copy for smoke tests and offline runs. A normal /insight report should include this JSON.

Claude /insights Reference Shape

Claude Code's /insights implementation uses a two-phase approach:

1. Deterministic local collection: scan session files, cache session metadata,

aggregate tool usage, code-change signals, errors, response timing, projects, and message/time patterns.

1. Optional narrative synthesis: feed a compact aggregate context to model calls

for sections such as work areas, interaction style, what works, friction, suggestions, and at-a-glance summary.

For Codex, preserve that shape while keeping phase 2 low-cost: pass only the summary JSON to a cheap/fast subagent or model, then inject the returned JSON into the HTML. The script's deterministic fallback remains available for fast or offline runs, with Markdown kept as a compatibility output.

Limitations

This is a local log analyzer, not an account billing source. It reports what the local Codex session files contain. Pricing estimates are intentionally omitted because model prices and billing rules can change; verify current official pricing before converting tokens to dollars.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ypwcharles
• Source: ypwcharles/codex-insight-skill
• License: MIT

Install and usage instructions live in the source repository linked above.