Codex Token Usage

English | 简体中文

Audit and visualize token activity recorded in local Codex session logs. The project provides a bilingual terminal dashboard, script-friendly text and JSON reports, rolling or custom time ranges, and import-aware counting that excludes historical Claude Code sessions without losing genuine Codex usage after an imported thread is continued.

This is an independent community project and is not affiliated with or endorsed by OpenAI.

Features

• Full-screen terminal UI with Chinese and English interfaces
• Press l in the UI to switch languages instantly
• Press Tab in the UI to switch between daily usage and effort analysis
• Rolling 24 hours, last 7 days, last 30 days, all history, and custom date ranges
• Conventional charts using dates for multi-day ranges and hours for complete single-day ranges
• Drill-down navigation from multi-day buckets to dates and hourly details without typing a date
• Human-readable Chinese or English text output
• Stable JSON output with schema_version: 1
• Root and subagent usage breakdowns
• Structured exclusion of imported Claude Code history
• Duplicate-snapshot handling and explicit integrity warnings
• Persistent incremental scan cache with an explicit forced-rescan path
• No prompts, responses, API keys, session IDs, or source paths in reports

Installation

Python 3.11 or newer is required.

Install directly from GitHub with pipx:

pipx install git+https://github.com/catchmeee2002/codex-token-usage.git

Or install from a clone:

git clone https://github.com/catchmeee2002/codex-token-usage.git
cd codex-token-usage
python3 -m pip install .

The runtime uses only the Python standard library on Unix-like systems. Windows installs windows-curses and the IANA tzdata package automatically.

Quick start

Open the interactive dashboard:

codex-token-usage

Controls:

Key	Action
↑ / ↓ or j / k	Select a time range
← / →	Select a chart bar and show its exact total
[ / ]	Select date bars, or switch days while viewing hourly details
Enter	Apply another menu range, or drill into the selected date bucket
Backspace	Return to the previous chart level
r	Refresh using file-change detection and incremental parsing
R	Force a full disk rescan and rebuild the scan cache
l	Switch between Chinese and English
Tab or e	Switch between usage and effort-analysis pages
q or Esc	Exit

Start the UI in English explicitly:

codex-token-usage --ui --lang en

Text and JSON reports

Passing a report option uses non-interactive text mode. Without a time option, text mode covers only the rolling last seven days and clearly labels that scope.

# Chinese text, rolling last seven days
codex-token-usage --text

# English text
codex-token-usage --text --lang en

# All recorded history
codex-token-usage --all

# Other rolling windows
codex-token-usage --since 24h
codex-token-usage --since 2w

# Inclusive local dates
codex-token-usage \
  --from 2026-07-18 \
  --to 2026-07-25 \
  --timezone Asia/Shanghai

# Hourly distribution for one local calendar day
codex-token-usage \
  --from 2026-07-25 \
  --to 2026-07-25 \
  --timezone Asia/Shanghai

# Machine-readable output
codex-token-usage --all --json

Important options:

Option	Purpose
--ui	Open the full-screen terminal UI
--text	Force non-interactive text output
--lang {zh,en}	Select the initial UI or text language
--all	Scan all recorded history
--since DURATION	Select a rolling window such as 24h, 7d, or 2w
--from ISO / --to ISO	Select a custom range
--timezone IANA	Set the timezone for date parsing and time buckets
--json	Emit stable machine-readable output
--no-daily	Hide the usage distribution chart in text output
--strict	Return non-zero when integrity or authentication warnings occur
--codex-home PATH	Override CODEX_HOME and ~/.codex discovery
--rebuild-cache	Ignore cached evidence, rescan every session file, and rebuild the cache
--no-cache	Do not read or write the scan cache for this run

Scan cache

The default scanner checks every session file's metadata, reuses unchanged parsed evidence, and reads only the appended suffix of growing JSONL files. It still reloads authentication and import records and reruns counting, import-boundary, and cross-file deduplication logic on every report.

The disposable SQLite cache is stored at $CODEX_HOME/.cache/codex-token-usage/evidence-v1.sqlite3. It contains only counting evidence and derived session metadata, not prompts, responses, or API keys. Delete it at any time, use --rebuild-cache, or press R in the UI to rebuild it from disk. Cache corruption or an unwritable cache location falls back to a correct full scan.

How counting works

Codex rollout logs are append-only activity records, not billing exports. Summing every total_tokens value would overcount because snapshots can repeat, resumed threads can inherit an existing cumulative value, and imported histories can include synthetic estimates.

The scanner therefore:

1. Reads the first session_meta record as the owner of each rollout file.
2. Counts last_token_usage only when the structured cumulative counter advances.
3. Excludes inherited parent-accounting events copied into a forked subagent before its first structured task trigger, while retaining the subagent's genuine requests and inherited-context input usage.
4. Deduplicates exact event copies across files.
5. Uses external_agent_session_imports.json and Codex's imported-session marker to exclude pre-import history.
6. Continues counting genuine Codex calls made after an imported thread is resumed.

total_tokens means input_tokens + output_tokens. Cached input is a subset of input, and reasoning output is a subset of output.

Limitations

• Local session logs are usage evidence, not a provider billing statement.
• Historical logs do not identify which API key produced each request.
• The tool does not estimate cost because pricing and organization-level accounting are not stored in local logs.

Development

python3 -m pip install -e '.[dev]'
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest -q
python3 -m build

See CONTRIBUTING.md before opening a pull request. Security issues should follow SECURITY.md. Project changes are recorded in CHANGELOG.md.

License

MIT