| name | codex-local-token-usage |
| description | Use when a user wants to audit token usage from local Codex session archives, especially for daily or monthly totals and cached versus uncached token breakdowns. |
Codex Local Token Usage
Use this skill when a user asks for local Codex token usage reporting.
When To Use
- The user asks how many tokens they used in Codex over a day, week, or month.
- The user wants totals grouped by day, session, or project directory.
- The user wants cached input separated from uncached usage.
Do not use this skill for official billing or account-level usage questions.
Data Source Priority
- Prefer local session archives under
~/.codex/sessions/YYYY/MM/DD/*.jsonl.
- Use the CLI in this repository to parse and summarize them.
- If session archives are unavailable, state that the current tool does not yet implement a full SQLite fallback.
Reporting Rules
- Report both
total_tokens and uncached_tokens.
- Define
uncached_tokens as:
input_tokens - cached_input_tokens + output_tokens + reasoning_output_tokens
- If the user asks for averages, provide both calendar-day and active-day averages.
Commands
Use python3 on macOS/Linux and python on Windows.
Monthly summary:
python3 scripts/report_codex_usage.py --month 2026-03
Daily breakdown:
python3 scripts/report_codex_usage.py --month 2026-03 --group-by day
Project breakdown:
python3 scripts/report_codex_usage.py --month 2026-03 --group-by cwd
