# Codex Local Token Usage

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

- Skill: `gouzigouzi/codex-local-token-usage` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gouzigouzi/codex-local-token-usage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gouzigouzi/codex-local-token-usage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: gouzigouzi (https://skillmd.com/u/gouzigouzi)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/gouzigouzi/codex-local-token-usage

---


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

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

```bash
python3 scripts/report_codex_usage.py --month 2026-03
```

Daily breakdown:

```bash
python3 scripts/report_codex_usage.py --month 2026-03 --group-by day
```

Project breakdown:

```bash
python3 scripts/report_codex_usage.py --month 2026-03 --group-by cwd
```