Codex Token Usage#

Overview#

Use the bundled script to read local Codex session logs and produce a consistent token usage report. Prefer deterministic script output over ad hoc rg summaries.

Workflow#

1. Identify the reporting window from the user request.
   • If the user asks for "one month" or "last month" without naming a calendar month, use the last 30 local calendar days ending today.
   • If the user asks for "this month" or names a specific month, use that calendar month, clipped to today if it is the current month.
   • Use the user's timezone from context when available; default to the local machine timezone only if no timezone is provided.
2. Run scripts/codex_token_usage.py.
3. Report results in a table with these rows: total, input, cached input, output, reasoning output, non-cached input, net usage, cache hit rate, and daily average total.
4. Include the peak day and busiest week with exact dates.
5. State the net usage formula.

Script#

Run from the skill directory or pass an absolute script path:

bash

python scripts/codex_token_usage.py --days 30 --timezone Asia/Shanghai

Useful options:

bash

python scripts/codex_token_usage.py --start 2026-03-30 --end 2026-04-28 --timezone Asia/Shanghai
python scripts/codex_token_usage.py --month 2026-04 --timezone Asia/Shanghai
python scripts/codex_token_usage.py --codex-home C:\Users\admin\.codex --days 30
python scripts/codex_token_usage.py --days 30 --format json
python scripts/codex_token_usage.py --days 30 --format markdown --language en

If python is not on PATH, use the bundled Codex runtime if available:

bash

C:\Users\admin\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe scripts\codex_token_usage.py --days 30 --timezone Asia/Shanghai

Definitions#

• total: sum of last_token_usage.total_tokens across token_count events.
• input: sum of last_token_usage.input_tokens.
• cached input: sum of last_token_usage.cached_input_tokens.
• output: sum of last_token_usage.output_tokens.
• reasoning output: sum of last_token_usage.reasoning_output_tokens.
• non-cached input: input - cached input.
• net usage: non-cached input + output.
• cache hit rate: cached input / input.
• daily average total: total / number of local calendar days in the reporting range.

Avoid summing total_token_usage for each event because it is cumulative within a session and will overcount. Sum last_token_usage instead.

Response Format#

Use a concise Markdown table. Localize row labels to the user's language. For Chinese responses, use labels like total, Input, Cached input, Output, Reasoning output, non-cached Input, and net usage in Chinese where appropriate.

markdown

| Metric | Tokens | Notes |
|---|---:|---|
| Total | 730,366,547 | Sum of `total_tokens` |
| Input | 724,204,405 | Input tokens, including cached input |
| Cached input | 640,615,168 | Cached input tokens |
| Output | 3,239,893 | Output tokens |
| Reasoning output | 456,198 | Reasoning output tokens |
| Non-cached input | 83,589,237 | `Input - Cached input` |
| Net usage | 86,829,130 | `Non-cached input + Output` |
| Cache hit rate | 88.44% | `Cached input / Input` |
| Daily average total | 24,345,552 | `Total / days in range` |

Then add one sentence for the peak day and busiest week:

markdown

The peak day was 2026-04-01: 72,000,000 tokens.
The busiest week was 2026-03-30 to 2026-04-05: 244,371,620 tokens.

Use --format json when the result will feed another script, dashboard, automation, or report generator. Use Markdown for direct user answers.