capitaine/codex-usage-dashboard repository overview

⁠Local Usage Dashboard for Codex

Local Usage turns the Codex session metadata stored on your computer into a fast, privacy-conscious usage dashboard. It can run entirely on one machine, or several machines can send signed, minimized usage snapshots to an optional central dashboard.

Stable release 1.5.4⁠ · Docker image 1.5.4⁠ · Source code⁠ · AGPL-3.0-or-later⁠ · Changelog⁠ · CI status⁠

⁠Donate

If you like this project and want to support its ongoing development, you can buy me a coffee⁠. Donations are entirely optional; the dashboard remains free and open source.

⁠What it shows

• API-equivalent cost split between fresh input, cached input, and output;
• estimated ChatGPT Codex credits, including observed Fast-mode multipliers;
• projects, conversations, model calls, turns, duration, tokens, and cache rate;
• hourly, daily, monthly, and full-history activity charts;
• current and historical weekly quota periods with cumulative consumption and end-of-window forecasts;
• project, model, period, usage, and conversation filters;
• nine interface languages.

⁠New in 1.5.4

• GPT-6 Sol and GPT-6 Luna API pricing is available in current and historical calculations.
• Reporting agents recover from stale replay sequences after synchronization rejection.
• Recent releases added relational SQLite storage, faster history queries, and clearer loading and error states.

⁠Docker

The public image supports Linux AMD64 and ARM64 and runs as a non-root user:

capitaine/codex-usage-dashboard:1.5.4

docker pull capitaine/codex-usage-dashboard:1.5.4
docker compose up -d

The 1.5.4 and latest tags share OCI digest:

sha256:5a0076a20c3da2da39ba1f7e7dc37e74f45bdb01d90f62a85fa8b4287134b5e4

The published manifests include SBOM and provenance attestations. See the full README⁠ for scoped read-only mounts, PowerShell/macOS/Linux commands, Compose configuration, and hardened deployment examples.

⁠Deployment modes

• Local GUI: reads only this machine's Codex session metadata and serves the dashboard locally.
• Local GUI plus reporting: keeps the local interface while sending signed minimized snapshots to a configured hub.
• Headless reporting agent: sends minimized snapshots without opening an HTTP port.
• Central hub: aggregates independently signed machine snapshots through OpenAI Sites or a self-hosted server.

Local mode is the default. Nothing is sent to a hub unless MESH_HUB_URL is explicitly configured.

⁠Privacy and security

• The local server listens on 127.0.0.1 by default.
• Session files are opened read-only.
• The dashboard never needs an OpenAI API credential and never reads auth.json.
• Docker mounts only the session directories and title index, not the entire .codex directory.
• Browser responses use an explicit allowlist and exclude message text, file contents, local paths, parse details, and modification times.
• Mesh reporting removes disallowed fields before signing and transmission.
• Reporting machines never receive the private Site credential.
• There is no analytics, telemetry, external font, or CDN asset.

Each OpenAI Sites deployment is private to its authenticated owner. Every machine has its own revocable Ed25519 identity and enrolls with a short-lived one-time code.

⁠Documentation

• Complete project README⁠
• Install a reporting agent⁠
• Install the Windows supervised agent⁠
• Deploy the central dashboard with OpenAI Sites⁠
• Deploy the public Mesh ingress⁠

Local Usage is independent free software and is not affiliated with, endorsed by, or sponsored by OpenAI. “Codex” and “OpenAI” describe compatibility; their trademarks remain the property of their owners. The complete project is licensed under GNU AGPL version 3 or any later version.