Codex Token Usage

中文 | English

一个用于统计 Codex 桌面端本地会话 Token 用量的小工具。

中文

这是什么

这个工具会扫描本地 Codex 会话目录：

• ~/.codex/sessions
• ~/.codex/archived_sessions

然后读取每个会话最后一次 token_count.total_token_usage 事件，汇总出：

• input_tokens
• cached_input_tokens
• output_tokens
• reasoning_output_tokens
• total_tokens

同时还会生成一个自包含的 HTML 可视化报告，包含：

• 指标卡
• 按天趋势图
• 高消耗会话排行

功能

• 不需要 API Key
• 直接读取本地 Codex 会话记录
• 可作为 CLI 工具安装
• 支持终端汇总输出
• 支持按天统计
• 支持 JSON 导出
• 支持自包含 HTML 可视化
• 已配置 GitHub Actions 基础校验

环境要求

• Python 3.9+

不依赖第三方 Python 包。

安装

直接运行：

python3 codex_token_usage.py

或者安装成命令行工具：

pip install .
codex-token-usage

使用方式

默认运行：

python3 codex_token_usage.py

这会在终端输出统计结果，并生成：

./codex_token_usage_report.html

常用示例：

python3 codex_token_usage.py --by-day
python3 codex_token_usage.py --top-sessions 20
python3 codex_token_usage.py --json
python3 codex_token_usage.py --html report.html
python3 codex_token_usage.py --codex-home ~/.codex

安装后可直接使用：

codex-token-usage
codex-token-usage --by-day --top-sessions 20
codex-token-usage --json

后续更新并推送：

./publish.sh "Update report layout"

CI 校验

GitHub Actions 当前会执行：

• Python 语法编译检查
• 基于空 Codex 目录的 JSON 输出检查
• 基于空 Codex 目录的 HTML 报告生成检查

输出说明

• cached_input_tokens 属于输入 Token 的缓存命中部分，不应再额外叠加到 input_tokens
• reasoning_output_tokens 通常是输出 Token 的子集，不应重复计算
• 这是基于本地会话日志的估算值，不是官方账单值

主要文件

• codex_token_usage.py
• pyproject.toml
• .github/workflows/ci.yml
• assets/report-preview.svg
• sample_report.html

License

MIT

English

What it is

This is a small utility for estimating Codex desktop token usage from local session files.

It scans:

• ~/.codex/sessions
• ~/.codex/archived_sessions

Then, for each session, it reads the last token_count.total_token_usage event and aggregates:

• input_tokens
• cached_input_tokens
• output_tokens
• reasoning_output_tokens
• total_tokens

It also generates a self-contained HTML report with:

• summary cards
• daily usage trend chart
• top session rankings

Features

• No API key required
• Reads local Codex session history directly
• Installable as a CLI tool
• Terminal summary output
• Daily breakdown support
• JSON export
• Self-contained HTML visualization
• GitHub Actions CI for basic validation

Requirements

• Python 3.9+

No third-party Python dependencies are required.

Install

Run directly:

python3 codex_token_usage.py

Or install it as a CLI:

pip install .
codex-token-usage

Usage

Run with defaults:

python3 codex_token_usage.py

This prints a terminal summary and writes:

./codex_token_usage_report.html

Common examples:

python3 codex_token_usage.py --by-day
python3 codex_token_usage.py --top-sessions 20
python3 codex_token_usage.py --json
python3 codex_token_usage.py --html report.html
python3 codex_token_usage.py --codex-home ~/.codex

Installed CLI examples:

codex-token-usage
codex-token-usage --by-day --top-sessions 20
codex-token-usage --json

Push later updates:

./publish.sh "Update report layout"

CI

GitHub Actions currently runs:

• Python syntax compilation
• JSON output validation against an empty fixture Codex directory
• HTML report generation validation against an empty fixture Codex directory

Output Notes

• cached_input_tokens is part of input usage and should not be added on top of input_tokens
• reasoning_output_tokens is typically a subset of output usage and should not be double-counted
• This is a local estimate from session logs, not an official billing number

Key Files

• codex_token_usage.py
• pyproject.toml
• .github/workflows/ci.yml
• assets/report-preview.svg
• sample_report.html

License

MIT