codex-stats

codex-stats is a Bun + TypeScript CLI for inspecting local Codex session files.

bun run src/cli.ts sessions
bun run src/cli.ts summary --group month
bun run src/cli.ts sessions -n 10 -H

By default it reads ~/.codex/sessions/**/*.jsonl. You can pass another Codex directory as the first positional argument:

codex-stats sessions /path/to/.codex

Commands

• codex-stats sessions [codexDir] lists session-level stats.
• codex-stats summary [codexDir] aggregates stats by day, month, or model.

Options

• -s, --since YYYY-MM-DD
• -u, --until YYYY-MM-DD
• -m, --model <name>
• -w, --cwd <text>
• -n, --limit <n>
• -S, --sort start|end|wall|active|tokens
• -a, --asc
• -j, --json
• -c, --csv
• -H, --human formats token columns as compact values such as 1.25M
• -G, --active-gap-min <n>
• -g, --group day|month|model for summary

Token usage is read from the last non-empty token_count total snapshot in each session, so repeated token events are not double counted.

Packaging

Build a bundled Bun script:

bun run build
bun dist/codex-stats.js sessions -n 10 -H

Build a standalone executable for the current platform:

bun run build:binary
./dist/codex-stats sessions -n 10 -H

On macOS, Bun standalone executables may need code signing with JIT entitlements before they can be distributed or run on locked-down systems. See Bun's macOS code signing guide for the required entitlements and signing command.

Create an npm package tarball that can be installed by Bun users:

bun run pack:tarball

The npm package keeps src/cli.ts as the codex-stats bin, so users need Bun installed. The standalone executable from build:binary does not require a separate Bun runtime.