Codex Token Consumption Statistics

Quick Start (Recommended to Use Python Script)

This skill provides a parameterized Python script, eliminating the need to manually write SQL/JSON parsing code. The script is located in this directory as

codex_token_summary.py

, supporting flexible time ranges and output format control.

Common Commands

bash

# Simple table for the last 7 days (default)
python codex_token_summary.py

# Last 30 days
python codex_token_summary.py --days 30

# Custom date range
python codex_token_summary.py --start-date 2026-04-01 --end-date 2026-05-18

# Detailed format (including Token categories)
python codex_token_summary.py --days 7 --format detailed

# Output as JSON
python codex_token_summary.py --days 14 --output json

# Include weekends
python codex_token_summary.py --days 30 --no-exclude-weekends

Windows Environment Initialization

If Python is not installed on Windows, use the

setup_python_env.ps1

in the same directory to install and configure it with one click:

powershell

# Run PowerShell as administrator, then execute
.\setup_python_env.ps1

This script will automatically detect Python, download the official installation package from python.org, add it to PATH, and install dependencies required by the script (only

backports.zoneinfo

is needed when Python < 3.9).

Quick Reference for Script Parameters

Parameter	Description	Example
`--days N`	Last N days (default: 7)	`--days 30`
`--start-date YYYY-MM-DD`	Custom start date	`--start-date 2026-04-01`
`--end-date YYYY-MM-DD`	Custom end date	`--end-date 2026-05-18`
`--format simple\|detailed`	Output detail level (default: simple)	`--format detailed`
`--output json\|table`	Output type (default: table)	`--output json`
`--no-exclude-weekends`	Include weekends	`--no-exclude-weekends`
`--tz TIMEZONE`	Time zone (default: Asia/Shanghai)	`--tz America/New_York`

See

README_SCRIPT.md

in this directory for details.

Applicable Scenarios

This skill is used when users need to count the Token consumption of the local Codex / Codex Desktop over a period of time, especially when requiring tables output by task purpose, session, model, and Token type proportion.

Chinese output is used by default. Unless specified otherwise by the user, "last 7 days" refers to looking back 7 natural days.

Data Sources

Mainly reads two local data sources:

```
~/.codex/state_*.sqlite
```
- Table:
```
threads
```
- Purpose: Obtain thread ID, task purpose, project path, model, rollout file path, creation/update time, total Token count.
- Should find
```
state_*.sqlite
```
  under
```
~/.codex/
```
  , then determine which one is the state database based on the schema.
- Key fields:
  - id
  - rollout_path
  - cwd
  - title
  - preview
  - first_user_message
  - created_at
  - updated_at
  - tokens_used
  - model
  - reasoning_effort
  - agent_role
  - thread_source
Compatible source:
- The session name field in the old
```
~/.codex/session_index.jsonl
```
  is usually called
```
thread_name
```
  , which is only used when the state database is missing or cross-verification is needed.

~/.codex/sessions/**/*.jsonl

and

~/.codex/archived_sessions/*.jsonl

The path usually comes from
```
threads.rollout_path
```
; do not only scan
```
sessions/
```
, as older or archived sessions may be in
```
archived_sessions/
```
.
Purpose: Read
```
token_count
```
events and perform incremental statistics by event time.

Key events:

```
type == "event_msg"
```
in JSONL lines
```
payload.type == "token_count"
```
```
payload.info.total_token_usage
```

Access Method

Prioritize discovering available Codex state SQLite, then query thread metadata, and finally read JSONL files one by one according to

rollout_path

State database discovery rules:

Search for
```
state_*.sqlite
```
under
```
~/.codex/
```
.
Execute
```
.tables
```
or query
```
sqlite_master
```
on candidate files.
Select the file that contains the
```
threads
```
table.
Verify that the
```
threads
```
table contains at least these fields:
```
id
```
,
```
rollout_path
```
,
```
cwd
```
,
```
created_at
```
,
```
tokens_used
```
.
If multiple files match, prioritize the one with the latest modification time; if necessary, output a candidate list for user confirmation.
Do not use
```
logs_*.sqlite
```
as the main statistics source. The log database can be used for debugging, but project dimensions and rollout paths come from the
```
threads
```
table of the state database.

Example query:

bash

STATE_DB="$(find ~/.codex -maxdepth 1 -name 'state_*.sqlite' -type f -print | sort | tail -1)"
sqlite3 -json "$STATE_DB" \
  "select id, rollout_path, cwd, title, preview, first_user_message, tokens_used, created_at, updated_at, model, reasoning_effort, agent_role, thread_source from threads"

Note: Use script commands compatible with Windows PowerShell for queries on Windows

It is recommended to aggregate using the script instead of only using

threads.tokens_used

. The reason is that

threads.tokens_used

is a thread-level cumulative value, which cannot be split by day or broken down into types like cached input, output, reasoning, etc.

Time Range

Default specifications:

Time zone:
```
Asia/Shanghai
```
Current date is based on the runtime environment date.
"Last 7 days" means 7 natural days including today.
Exclude dates where
```
weekday >= 5
```
, i.e., Saturdays and Sundays.
Use the
```
timestamp
```
of JSONL
```
token_count
```
events to determine if they fall within the statistical range.

Example: If the current date is

2026-05-18

, the statistical range is from

2026-05-12

2026-05-18

, and the actual working days included are

2026-05-12

2026-05-13

2026-05-14

2026-05-15

2026-05-18

Aggregation Algorithm

For each rollout JSONL file:

Read the corresponding
```
threads
```
row and generate "task purpose" as the main dimension.
Sequentially read
```
token_count
```
events in JSONL.
```
total_token_usage
```
in each event is a cumulative value for the thread, not a single increment.
Calculate the difference between adjacent
```
token_count
```
events in the same file to get the increment of this event.
Only accumulate increments whose event time falls within the statistical working days.
Aggregate the total amount by "task purpose".
At the same time, retain details such as project path, model, session ID to facilitate explaining abnormal large amounts.

Task purpose generation rules:

Prioritize using
```
threads.title
```
.
If
```
title
```
is empty or obviously a system review/sub-agent long instruction, fall back to
```
threads.preview
```
.
If
```
preview
```
is also unavailable, fall back to the first line or first 80 characters of
```
threads.first_user_message
```
.
Retain
```
thread_source
```
and
```
agent_role
```
, because the task purpose of sub-agents usually comes from spawn instructions, which may not be equivalent to the user's original requirement.
Truncate overly long task purposes for display, but use the complete value as the aggregation key to avoid merging different tasks.

If a thread was created within the statistical range but no

token_count

events are found, it needs to be explained in the results instead of being silently ignored.

Token Categories

Fields that can be directly extracted from local Codex records:

```
input_tokens
```
```
cached_input_tokens
```
```
output_tokens
```
```
reasoning_output_tokens
```
```
total_tokens
```

Recommended output categories:

New Input/Retrieval Context

input_tokens - cached_input_tokens

```
Cached Input
```
:
```
cached_input_tokens
```

Output/Code Writing

output_tokens - reasoning_output_tokens

```
Reasoning
```
:
```
reasoning_output_tokens
```

Statistical Dimensions

Main dimension:

Task purpose: Prioritized from
```
threads.title
```
, fall back to
```
threads.preview
```
or
```
threads.first_user_message
```
if necessary.

Default metrics:

```
Project
```
```
Model
```
```
Total Tokens
```
```
Proportion
```
```
New Input/Retrieval Context
```
```
Cached Input
```
```
Output/Code Writing
```
```
Reasoning
```

Optional auxiliary dimensions:

Date
Session ID:
```
id
```
Project path:
```
cwd
```
Model:
```
model
```
Reasoning effort:
```
reasoning_effort
```
Sub-agent type:
```
agent_role
```
Thread source:
```
thread_source
```

Model

Model field:

Prioritize using
```
threads.model
```
.
If
```
threads.model
```
is empty, look for the model field from
```
turn_context.payload.model
```
in the rollout JSONL.
Do not treat
```
session_meta.payload.model_provider
```
as the model name; it is usually just the provider, e.g.,
```
openai
```
.
Prioritize using
```
threads.reasoning_effort
```
for reasoning intensity; if reading JSONL directly, use
```
turn_context.payload.effort
```
.
If multiple models appear under the same task purpose, list them with commas in the table, or display as
```
mixed: model-a / model-b
```
.

Output Format

First use a paragraph to explain the statistical specifications, then output the table. The "simple" scheme is output by default; the "detailed" scheme is only output when the user explicitly requests detailed classification, Token type proportion, or split of input/cache/output/reasoning.

Simple Scheme (Default)

First output the

Total

summary row, then the detailed table. The

Total

shows the total Token amount and 100% proportion.

markdown

**Total Tokens**: XXX (100%)

Fixed table fields:

Task Purpose	Model	Total Tokens	Proportion

Example:

markdown

| `Count project Token consumption in the last 7 days` | `gpt-5.5` | 255,187,782 | 99.55% |

The

Total

row is no longer included in the detailed table.

Detailed Scheme

When the user requests detailed output, first output the

Total

summary row, then the detailed table. The

Total

shows the aggregated value of each category and its percentage of the total amount.

markdown

**Total Tokens**: XXX (100%) | New Input/Retrieval Context: XXX (XX%) | Cached Input: XXX (XX%) | Output/Code Writing: XXX (XX%) | Reasoning: XXX (XX%)

The detailed table uses the complete current fields:

Task Purpose	Project	Model	Total Tokens	Proportion	New Input/Retrieval Context	Cached Input	Output/Code Writing	Reasoning

Each category field is recommended to be displayed as:

text

Amount (percentage of the total amount of this task)

Example:

markdown

| `Count project Token consumption in the last 7 days` | `/path/to/project` | `gpt-5.5` | 255,187,782 | 99.55% | 25,302,445 (9.91%) | 229,055,744 (89.76%) | 619,303 (0.24%) | 210,290 (0.08%) |

The

Total

row is no longer included in the detailed table.

Result Explanation

A paragraph of limitation explanation should be added after the table:

Data comes from the state database that conforms to the schema in the local
```
~/.codex/state_*.sqlite
```
, and rollout JSONL.
```
Cached Input
```
,
```
Output
```
,
```
Reasoning
```
in the categories are structured Token fields recorded by Codex.
Semantic types such as "search, code writing, file reading" do not have independent precise fields and can only be approximately explained through Token fields.
If there are threads with missing rollout files or missing
```
token_count
```
events, list the number of affected threads and their paths.

Recommended Verification

Perform two verifications after statistics are completed:

Check if there are threads created within the statistical range without
```
token_count
```
events.
Compare whether the total aggregated amount of projects is consistent with the sum of session incremental amounts.

codex-token-summary

NPX Install

Tags

SKILL.md Content (Chinese)

Codex Token Consumption Statistics

Quick Start (Recommended to Use Python Script)

Common Commands

Windows Environment Initialization

Quick Reference for Script Parameters

Applicable Scenarios

Data Sources

Access Method

Time Range

Aggregation Algorithm

Token Categories

Statistical Dimensions

Model

Output Format

Simple Scheme (Default)

Detailed Scheme

Result Explanation

Recommended Verification