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.

Screenshots

Framed captures of the current HTML report and shareable profile.

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, ~/.local/bin, ~/.npm-global/bin, ~/.cargo/bin, and ~/.codex/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 (API keys, classic and fine-grained GitHub tokens, AWS access keys, Slack tokens, npm tokens, bearer tokens, password assignments, private keys, and URL userinfo) and both slash forms of the home path are redacted before caches, prompts, JSON, and HTML. Pattern-based redaction cannot guarantee every sensitive fact is removed
• Report and profile files are written so only your user can read them (mode 0600)
• 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.