Codex Analytics Dashboard

Local-first analytics dashboard for Codex session logs. It reads your own Codex data from your machine, reconstructs daily token usage, sessions, message events, observable plugin and skill executions, model mix, output ratio, heatmaps, top sessions, top projects, and what-if API cost estimates, then renders a self-contained HTML dashboard.

No data is uploaded. The dashboard is generated locally from your local Codex files.

Requirements

• Node.js 18 or newer for the npx launcher.
• Python 3.10 or newer for the dashboard generator.
• Local Codex session data in ~/.codex, or a custom path passed with --codex-home.

Quick Start

npx codex-analytics-dashboard@latest

The npx launcher starts a localhost dashboard server, opens the dashboard in your browser, and writes generated files to a user-local application data directory. Browser refresh regenerates the dashboard from the latest local logs while the server is running.

Updating

If you use npx codex-analytics-dashboard@latest, updating is just running the same command again:

npx codex-analytics-dashboard@latest

The saved snapshot configuration is not overwritten. The dashboard keeps using the same user-local app config and the same synced Codex Analytics folder, then refreshes this device's snapshot.json on launch or browser refresh.

If you installed the command globally, update the global package first:

npm install -g codex-analytics-dashboard@latest
codex-analytics-dashboard

You only need to pass --snapshot-dir and --device-name again when setting up a new device, changing the synced folder, or renaming the device.

Install it globally if you prefer a reusable command:

npm install -g codex-analytics-dashboard
codex-analytics-dashboard

You can also run the Python generator directly:

python3 codex_usage_dashboard.py --serve

Data Sources

By default, the dashboard reads:

• ~/.codex/sessions
• ~/.codex/archived_sessions
• ~/.codex/state_5.sqlite

Override the Codex data directory when needed:

npx codex-analytics-dashboard@latest -- --codex-home ~/.codex
python3 codex_usage_dashboard.py --codex-home ~/.codex --serve

Useful Options

npx codex-analytics-dashboard@latest -- --timezone Europe/Berlin
npx codex-analytics-dashboard@latest -- --no-open
npx codex-analytics-dashboard@latest -- --redact
npx codex-analytics-dashboard@latest -- --snapshot-dir ~/Dropbox --device-name "Work MacBook"
python3 codex_usage_dashboard.py --out ~/Desktop/codex_analytics_dashboard.html
python3 codex_usage_dashboard.py --serve --port 8765
python3 codex_usage_dashboard.py --serve --no-open
python3 codex_usage_dashboard.py --no-json

--redact also works as --privacy. It masks session titles, thread IDs, local paths, and source metadata in the generated dashboard output. Use it when creating screenshots or a shareable local export.

Multi-Device Snapshots

Do not put your full ~/.codex directory in Dropbox, iCloud, Syncthing, or any other shared folder. It can contain private prompts, responses, local paths, auth/config files, and raw session logs.

Use a synced parent directory instead. The dashboard creates a Codex Analytics folder inside it automatically:

npx codex-analytics-dashboard@latest -- --snapshot-dir ~/Dropbox --device-name "Work Windows"

Run the same setup once on each device, pointing all devices at the same synced folder and giving each device a clear name:

npx codex-analytics-dashboard@latest -- --snapshot-dir ~/Dropbox --device-name "Personal MacBook"

The snapshot path is saved in the user-local app config, so future dashboard launches update the same folder automatically. Each launch or localhost refresh reads the local ~/.codex, writes a reduced snapshot for the current device, then aggregates all snapshots found in:

Dropbox/
  Codex Analytics/
    work-windows/
      device.json
      snapshot.json
    personal-macbook/
      device.json
      snapshot.json

If you pass a folder already named Codex Analytics, CodexAnalytics, or codex-analytics, that folder is used directly instead of creating another nested folder.

Snapshots include dashboard-level analytics only: token/time series, model usage, cost estimates, message/session counts, observable plugin/skill execution counts, session titles, and project names. They do not include prompts, responses, tool output, raw rollout logs, SQLite databases, source metadata, full filesystem paths, or auth/config files. Project names are reduced to the final folder name, such as codex-analytics-dashboard.

Snapshot schema 2 starts with dashboard version 0.2.8. Older snapshots are ignored because their subagent token totals cannot be corrected safely after aggregation. Launch or refresh version 0.2.8 or newer once on every device to repopulate the multi-device view.

The dashboard defaults to All devices and includes a device selector in the header so you can filter the full view down to one device.

Project Aliases

Codex stores the working directory name that was active when a session ran. If you rename a folder later, old sessions can still appear under the historical project name.

The dashboard automatically groups projects with the same final folder name across devices and paths. Case, hyphens, underscores, and extra spaces are ignored, so My Project, my-project, and my_project are treated as the same project.

For true renames, use project aliases. The dashboard automatically creates a user-local project_aliases.json file next to its config:

• macOS: ~/Library/Application Support/Codex Analytics Dashboard/project_aliases.json
• Linux: ${XDG_STATE_HOME:-~/.local/state}/codex-analytics-dashboard/project_aliases.json
• Windows: %LOCALAPPDATA%/Codex Analytics Dashboard/project_aliases.json

You can add aliases from the command line:

npx codex-analytics-dashboard@latest -- --project-alias "Old project name=New project name"

Or edit project_aliases.json directly:

{
  "version": 1,
  "projects": [
    {
      "name": "Current Project Name",
      "aliases": [
        "Old Project Name",
        "C:/old/path/Old Project Name"
      ]
    }
  ]
}

Aliases are applied when the dashboard aggregates sessions and snapshots. They only affect dashboard output; Codex logs, source folders, and synced snapshots are not rewritten.

Outputs

The Python defaults write to the current directory:

• codex_analytics_dashboard.html - interactive dashboard.
• codex_analytics_data.json - machine-readable export.

The npx launcher writes to a user-local application data directory:

• macOS: ~/Library/Application Support/Codex Analytics Dashboard
• Linux: ${XDG_STATE_HOME:-~/.local/state}/codex-analytics-dashboard
• Windows: %LOCALAPPDATA%/Codex Analytics Dashboard

Opening codex_analytics_dashboard.html directly as a file:// page shows a static snapshot. Use --serve when you want browser refresh to update data.

Privacy

Generated dashboard files can contain private local usage data: session titles, thread IDs, model usage, timestamps, local filesystem paths, and project names. Keep generated HTML/JSON files out of commits, issues, screenshots, and public releases unless you intentionally generated them with --redact and reviewed the result.

This project is a local analysis tool, not a billing mirror. The cost view is a what-if estimate using public OpenAI API token prices. It is not ChatGPT or Codex subscription billing.

API prices are versioned by effective date. Usage is grouped by event date before costs are calculated, so a later price change does not rewrite the estimate for earlier usage. The dashboard currently uses standard, short-context text-token prices; it does not apply Batch, Flex, Priority, regional-processing, cache-write, or long-context surcharges.

Thread-spawn rollout counters are inherited task-tree totals, so the dashboard books them only through the root Codex session. Child rollouts still contribute message activity and observable plugin/skill executions. The plugin leaderboard is intentionally conservative: it includes identifiable plugin/MCP namespaces and SKILL.md activations, while generic wrapper tools are excluded. It is not a mirror of OpenAI's private analytics schema.

Release Notes

0.2.8

• Added the July 30, 2026 GPT-5.6 Luna and Terra price reductions as new effective-dated rows; earlier usage keeps the launch prices.
• Fixed multi-billion-token spikes by treating thread-spawn counters as inherited task-tree rollups and counting usage only in the root Codex session.
• Added support for replay-only child prefixes that omit the copied parent's session_meta row.
• Added a range- and device-aware top-six leaderboard for locally observable plugins and skills.
• Bumped privacy-preserving multi-device snapshots to schema 2 so stale inflated snapshots are not mixed with corrected data.
• Reduced parser work by skipping rollout rows that cannot affect dashboard analytics.

0.2.7

• Added GPT-5.6 Sol (gpt-5.6 / gpt-5.6-sol), Terra, and Luna API-equivalent pricing.
• Added effective-date price histories and date-aware costs across local data, synced snapshots, filters, charts, sessions, projects, and model totals.
• Added official GPT-5.3 Codex pricing for the GPT-5.3/Codex log variants already recognized by the parser.
• Added GPT-5.6 none and max reasoning-effort labels.
• Fixed inflated token totals from forked subagent rollouts by treating replayed parent history as the child's cumulative baseline instead of new usage.
• Added Windows-friendly Python discovery in the NPM launcher (py -3, python, then python3; PYTHON still overrides it).
• Preserved the existing 0.2.6 dashboard privacy, project-alias, range, and KPI refinements, with displayed paths now covered by the privacy toggle as well.

Development

python3 -m py_compile codex_usage_dashboard.py
python3 -m unittest
node --check bin/codex-analytics-dashboard.js
npm pack --dry-run

To verify empty-state behavior:

python3 codex_usage_dashboard.py --codex-home /tmp/empty-codex-home --out /tmp/codex_analytics_dashboard_empty.html --json-out /tmp/codex_analytics_data_empty.json --timezone UTC

License

MIT