Codex Insights: /insights for OpenAI Codex

Claude Code has /insights. Codex doesn't, so this open-source $insights skill adds it: a private report on how you work with Codex, plus a public profile page you can share.

• Private workflow report. Type $insights in Codex for an HTML report on your projects, tools, friction, and what to try next. It runs offline with zero model calls by default.
• Shareable Codex profile. codex-session-insights profile turns the stats from the Codex app's private Settings → Profile page (lifetime tokens, streaks, token activity, top skills and plugins) into a page you can publish. Live example.
• Stays current by itself. codex-session-insights schedule install updates the CLI and skill when a new release ships, and can republish your profile on a schedule.

curl -fsSL https://raw.githubusercontent.com/mangeshraut712/codex-insights/HEAD/scripts/install.sh | bash

Then start a new Codex thread and type $insights. Built and maintained by Mangesh Raut; contributions are welcome (CONTRIBUTING.md).

Private HTML and JSON reports from your local Codex sessions. Use $insights in Codex or the codex-session-insights CLI. An unspecified $insights request defaults to --local-only (deterministic metrics, zero model calls); the CLI still estimates before a model-assisted run unless you pass --local-only.

Landing surface of a real HTML report: header stats, Trust & Coverage, and At a Glance.

Deeper sections from the same report: workstreams, usage patterns, and what went well.

This is a community continuation of cosformula/codex-session-insights. It is inspired by Claude Code /insights: a report on how you work on this machine, not a token bill. Codex has no native /insights. Mapping: docs/claude-insights.md. Claude’s /insights is model-assisted; ask for --yes only when you want that kind of narrative.

The plugin follows the official Codex plugin ingestion contract (manifest, skill, storefront assets, validate_plugin.py). It is a community listing, not an OpenAI-published directory tab. See docs/plugin-directory.md.

Install $insights

codex plugin marketplace add mangeshraut712/codex-insights
codex plugin add codex-insights@codex-insights

Start a new Codex thread and type $insights.

CLI and skill together:

curl -fsSL https://raw.githubusercontent.com/mangeshraut712/codex-insights/HEAD/scripts/install.sh | bash

CLI only (no global install):

npx github:mangeshraut712/codex-insights --local-only

Update, uninstall, and from-source steps: docs/install.md.

Use

In Codex, $insights with no extra wording builds a local-only report. Ask for an estimate or a model-assisted report when you want those routes. The skill does not share reports or apply recommendations unless you ask separately.

For a web-shareable activity profile, ask $insights to create a profile or run codex-session-insights profile. It exports the same stats as the Codex app's private Settings → Profile page (lifetime tokens, streaks, token activity, activity insights, most used skills and plugins) as a self-contained, aggregate-only page plus profile.json. See the live example and Shareable profile for review and GitHub Pages publishing steps.

After the CLI is on PATH:

codex-session-insights --local-only      # private, zero model calls
codex-session-insights --estimate-only   # token range, no generation
codex-session-insights --yes             # model-assisted after you confirm

Reports write to ~/.codex/usage-data/ (Claude analogue: ~/.claude/usage-data/):

• report.html / report.json — latest run
• report-<stamp>.html / report-<stamp>.json — timestamped copies; copies older than 30 days are removed at startup and on the next write
• seen-sessions.json / session-summaries/ — journal of sessions already analyzed so later runs can reuse them

HTML header coverage matches Claude: 200 sessions (412 total) when some discovered sessions are left out (short threads, source filters, unseen cap, or reused history that still leaves newer sessions unread). HTML sections: Trust & Coverage, At a Glance, What You Work On, How You Use Codex, Impressive Things You Did, Where Things Go Wrong, Features to Try, On the Horizon, One More Thing.

The interactive CLI flow is:

1. Read your local Codex thread index on this machine
2. Estimate likely analysis token usage (skipped with --local-only)
3. Confirm the plan in a TTY (skipped with --yes or --local-only)
4. Write HTML and JSON, plus a timestamped copy
5. Try to open the latest HTML report

Usage

codex-session-insights --preset lite
codex-session-insights --days 7 --limit 20 --facet-limit 8 --estimate-only
codex-session-insights --days 0 --local-only
codex-session-insights --since 2026-09-01 --local-only
codex-session-insights --version
codex-session-insights schedule install --repo you/codex-profile   # auto-update skill + profile (macOS)
codex-session-insights --reanalyze --local-only
codex-session-insights --out-dir ./insights-output
codex-session-insights --stdout-json
codex-session-insights --include-archived
codex-session-insights --include-subagents
codex-session-insights --data-source app-server
codex-session-insights --data-source legacy
codex-session-insights --lang zh-CN
codex-session-insights --lang en
codex-session-insights --provider openai --api-key "$OPENAI_API_KEY"
codex-session-insights --no-open
codex-session-insights --open

auto is the default data source: app-server first, with a visible warning if it falls back to the legacy reader. --app-server-timeout 30000 changes the per-request timeout.

Without a global install, prefix the same flags with npx @mangeshraut712/codex-insights (or npx github:mangeshraut712/codex-insights). The unscoped codex-session-insights npm package is an older upstream release.

Defaults

• days: 30 (0 = all local sessions on this machine)
• limit: 200 (max unseen substantive sessions to read this run; earlier analyses are reused)
• facet-limit: 50 (uncached per-thread facet analyses in one report)
• provider: codex-cli
• facet-model / fast-section-model: gpt-5.4-mini
• insight-model: gpt-5.4
• facet-effort / fast-section-effort: low
• insight-effort: high
• --preset lite → days=7, limit=20, facet-limit=8, preview=10
• Report language follows a best-effort system locale
• Main threads only; pass --include-subagents to include delegated sources
• $insights defaults to --local-only; the CLI wizard still estimates before a model-assisted run

Override the model split:

codex-session-insights \
  --facet-model gpt-5.4-mini \
  --fast-section-model gpt-5.4-mini \
  --insight-model gpt-5.4 \
  --facet-effort low \
  --fast-section-effort low \
  --insight-effort high

What it reads

• Codex app-server thread/list and thread/read in default auto mode
• ~/.codex/state_*.sqlite and rollout JSONL only for --data-source legacy or a recorded auto fallback

Collection is read-only. The CLI does not start turns or change session state. See App-server compatibility.

Requirements

• Node.js >=18.17.0
• Codex CLI for $insights and for the default codex-cli provider
• sqlite3 on PATH only for legacy mode

macOS and Linux are expected to work. Windows is not yet verified. On macOS, $insights looks for codex and codex-session-insights under /opt/homebrew/bin, /usr/local/bin, and ~/.local/bin in addition to PATH, so Codex Desktop can still spawn app-server after Homebrew installs.

Privacy

The tool reads local Codex data on your machine.

• --local-only (the $insights default): no model is called
• provider=codex-cli: analysis uses your local Codex CLI session
• provider=openai: prompts go to the OpenAI Responses API
• Recognized credentials and home paths are redacted before caches, prompts, JSON, and HTML. Pattern-based redaction cannot guarantee every sensitive fact is removed
• Reports may still contain project names, thread titles, and other local development context

Review report.html and report.json before sharing. See Privacy and trust, the privacy policy, and terms.

Limitations

• Rollout and app-server schemas may drift across Codex versions
• Token estimates are conservative, not billing-accurate
• Model-assisted narratives are interpretations; incomplete collection also limits deterministic reports
• This is not a generic agent-log analyzer
• Windows support is not yet verified

Docs and contributing

User and contributor guides: docs/README.md.

npm ci
npm run ci
npm run generate:test-report
bash scripts/install.sh

Analyzer changes follow docs/contributing-analyzers.md. A native /insights command is an unaccepted proposal, not a shipped Codex feature. Maintainers are mangeshraut712 and Cursor only; automated GitHub dependency bots are not used.