Codex Token Usage

Summarize Codex token usage from local Codex Desktop or CLI session JSONL logs. Use when the user asks to count, audit, total, compare, or report Codex/OpenAI token usage for a period such as today, this week, last month, a calendar month, a rolling 30-day window, peak week, peak day, input/output/cached/reasoning breakdown, or net 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:

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

Useful options:

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:

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.

| 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:

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.