codex-local-token-usage

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

1. Prefer local session archives under ~/.codex/sessions/YYYY/MM/DD/*.jsonl.
2. Use the CLI in this repository to parse and summarize them.
3. 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