A web dashboard and CLI tool for tracking OpenAI Codex CLI token usage with enterprise credit tracking and billing.
- Token Usage Tracking: Monitor daily and weekly Codex token consumption
- Credit Pool Management: Track usage against configurable weekly credit allocations
- Interactive Dashboard: Visualize usage patterns over time with an interactive web interface
- CLI Commands: Quick access to usage summaries from the terminal
- Multi-Project Support: Group multiple git repos under one project; track OAuth and API-token projects separately with different billing modes
codexusage week
Codex Usage — week of 2025-05-02
------------------------------------------------------------
Model Tokens USD Credits
---------------------- ------------ --------- ----------
gpt-5 234,567 $0.7248 18.12 cr
o4-mini 98,432 $0.2184 5.46 cr
---------------------- ------------ --------- ----------
Total 333,099 $0.9432 23.58 cr
Pool: [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 23.58 / 2500 cr (0.9%)
Run
codexusage dashboardand take a screenshot, then replace this line with.
pipx install git+https://github.com/andyfloyd86/codexusage.gituv tool install git+https://github.com/andyfloyd86/codexusage.gitpip install git+https://github.com/andyfloyd86/codexusage.gitcodexusage config initThis writes ~/.config/codexusage/config.json with auto-detected defaults. Then
customise as needed:
codexusage config set --weekly-pool 2500 --credits-per-dollar 25codexusage todaycodexusage week # current billing week (Fri 17:00 → Fri 17:00)
codexusage week --weeks 4 # last 4 weekscodexusage dashboardOpens http://localhost:8080 automatically. Press Ctrl-C to stop.
Print today's token and credit summary, or a custom date range.
codexusage today
codexusage today --since 2025-01-01 --until 2025-02-01Print weekly summary. Billing week resets every Friday at 17:00.
codexusage week
codexusage week --weeks 4
codexusage week --since 2025-01-01 --until 2025-02-01Start the interactive web dashboard.
| Option | Default | Description |
|---|---|---|
--port |
8080 | Override the configured port |
--no-open |
false | Don't open the browser automatically |
Write a default config file to ~/.config/codexusage/config.json.
| Option | Description |
|---|---|
--sessions-dir PATH |
Path to Codex sessions directory |
--weekly-pool N |
Weekly credit pool size |
--credits-per-dollar N |
Credits per $1 of token spend |
--port N |
Dashboard port |
A project covers one CODEX_HOME (sessions directory) and one or more git repo checkouts. Events are assigned to a project by matching the session's working directory against the project's declared repos (prefix match). When multiple projects share the same sessions directory, repos are used to route events to the right project.
# OAuth project with two repos sharing one CODEX_HOME
codexusage config project add \
--name work \
--home ~/.codex \
--auth-type oauth \
--repo ~/code/repo_a \
--repo ~/code/repo_b
# API-token project (billed in USD, shown separately)
codexusage config project add \
--name personal \
--home ~/personal/.codex \
--auth-type api_token
# Add / remove a repo from an existing project
codexusage config project add-repo work ~/code/repo_c
codexusage config project remove-repo work ~/code/repo_b
codexusage config project list
codexusage config project remove --name personal~/.config/codexusage/config.json:
{
"weekly_pool_credits": 2500,
"credits_per_dollar": 25,
"sessions_dir": "~/.codex/sessions",
"port": 8080,
"projects": [
{
"name": "work",
"sessions_dir": "~/.codex/sessions",
"auth_type": "oauth",
"repos": ["/home/user/code/repo_a", "/home/user/code/repo_b"]
}
]
}Requires Python 3.10+ and uv.
git clone https://github.com/andyfloyd86/codexusage.git
cd codexusage
uv sync --group dev # create .venv and install all deps
uv run codexusage --help # run from the local checkout
uv run pytest # tests
uv run ruff check src tests # lint
uv run ruff format src tests # format
uv run mypy src/codexusage # type-checkCI runs lint + type-check + tests on every push via GitHub Actions (.github/workflows/ci.yml).
- Session Scanning: Parses Codex JSONL session logs in
sessions_dir - Token Counting: Aggregates tokens by model, day, and project
- USD Conversion: Uses bundled OpenAI pricing (
pricing.json) to calculate cost - Credit Conversion: Converts USD → credits using your configured
credits_per_dollarrate - Visualization: Dashboard renders per-day charts, model breakdowns, and pool utilization
sessions_dir not found — Check the path:
codexusage config set --sessions-dir ~/.codex/sessionsNo usage data showing — Verify Codex CLI has been used and session files exist:
ls ~/.codex/sessions/Dashboard port in use — Use a different port:
codexusage dashboard --port 9090- Python 3.10+
- Codex CLI installed and used at least once
- No external Python dependencies (stdlib only)
codexusage/
├── src/codexusage/
│ ├── cli.py # CLI entry point and argument parsing
│ ├── server.py # HTTP server for the web dashboard
│ ├── scanner.py # JSONL session log parser
│ ├── pricing.py # Token → USD conversion
│ ├── config.py # Config file management
│ ├── pricing.json # Bundled OpenAI pricing data
│ └── web/ # Dashboard HTML/CSS/JS (ECharts)
├── tests/ # pytest test suite
├── scripts/ # Dev utilities (test data generation)
├── .github/workflows/ # CI (lint, type-check, test)
└── pyproject.toml # Build metadata and tool config
MIT