Local stats dashboard for Codex. Read usage directly from machine logs and use codex stats like it was built into Codex.

Works on:

• Windows x64 and arm64
• macOS Intel and Apple Silicon
• Linux x64 and arm64

Requirements:

• Node.js 18+
• Codex already installed on the machine

Install once:

npm install -g codex-observatory

Then use it like this:

codex stats
codex stats compact
codex stats full
codex stats --json

Global npm install auto-runs the Codex integration step and patches the local codex launcher so codex stats works immediately.

If your npm install was run with scripts disabled, or Codex was not installed yet, repair the setup with:

codex-observatory install-codex --patch-codex

These direct commands are still available and map to the same dashboard:

• codex-observatory
• codex-stats

Examples:

codex-observatory compact
codex-stats --json

codex-observatory uninstall-codex
npm uninstall -g codex-observatory

The first command removes the Codex integration and restores the patched codex launcher. The second command removes the global npm package.

• npm install -g codex-observatory is the main supported user flow.
• npm uninstall -g codex-observatory removes the npm package itself, but npm does not run uninstall lifecycle hooks for packages. Run codex-observatory uninstall-codex first for a clean rollback.
• npm installs download the matching native binary automatically.
• If history.jsonl is missing, Codex Observatory rebuilds prompt history from session logs.
• If sessions/ is missing but history.jsonl exists, Codex Observatory still renders prompt and session counts and falls back to zero token totals plus unknown model metadata.

• Install Guide
• Usage Guide
• Codex Integration
• Changelog