Codex Usage Audit

Local, privacy-preserving token, context, and cost telemetry for Codex conversations.

Open source under the MIT License.

Codex Usage Audit answers the questions that become important during long agentic tasks:

• Which model and service tier did this conversation use?
• How many input, cached-input, cache-write, output, and reasoning tokens were consumed?
• How much of the input was served from cache?
• What was the highest observed context-window pressure?
• How many tool calls and subagent sessions were involved?
• What is the estimated cost in Codex credits?
• What would the same token usage cost at public API Standard list prices?
• How much did the model round that invoked Usage Report cost?
• Should the task continue, be summarized, start fresh, or be split?

The plugin reads local Codex rollout files, computes aggregate usage metrics, and can display a compact report automatically whenever a turn stops. It never emits transcript content; JSON output does include operational metadata such as task identifiers, timestamps, warnings, and the resolved rate-card path.

Important

Cost values are estimates, not billing records. Codex credits and API prices are separate rate systems. Credits have no cash value, and the API-equivalent value is not a ChatGPT charge or a credits-to-USD conversion.

Contents

• Highlights
• Example output
• Installation
• Usage
• How the metrics work
• Usage Report command cost
• Performance and local cache
• Rate-card configuration
• Privacy and security
• Development
• Limitations
• Contributing
• License

Highlights

• Conversation and task scopes — compare the entire parent conversation with the current parent turn and its descendant subagents.
• Exact and readable quantities — keep the exact count and add magnitude notation such as 78,521,555 (78.52M).
• Cache visibility — report cache reads, cache writes, and cache ratio without double-counting input-token details.
• Context pressure — track the highest and latest observed request size relative to the model context window.
• Two independent cost views — estimate Codex credits and a separate API Standard short-context equivalent.
• Auditable cost breakdown — split cost into uncached input, cached input, API cache-write premium, and output.
• Self-observation — measure the completed model round that invoked usage_report.py, including its token mix and effective tokens per credit.
• Automatic reporting — a bundled Stop hook displays a compact summary after each Codex turn.
• Fast repeat scans — reuse a private aggregate cache for unchanged rollouts and index descendant sessions once per report.
• Machine-readable output — emit the same report as JSON with raw numeric values and explicit operational metadata.
• Local-only runtime — Python standard library only; no telemetry server and no runtime network request.

Example output

The Markdown report starts with a conversation/task comparison:

Metric	Conversation	Current task
Model(s)	gpt-5.6-sol	gpt-5.6-sol
Input tokens	78,156,574 (78.16M)	2,517,177 (2.52M)
Cached input	75,055,104 (75.06M)	2,430,208 (2.43M)
Cache writes	0	0
Output tokens	364,981 (364.98K)	26,687 (26.69K)
Total tokens	78,521,555 (78.52M)	2,543,864 (2.54M)
Cache ratio	96.0%	96.5%
Tool calls	433	24
Estimated Codex cost	~1,599.61 cr (1.6K cr)	~61.26 cr
API-equivalent cost	~$63.98	~$2.45

The report ends with the cost of the model round that invoked Usage Report:

Metric	Example value
Input tokens	138,829 (138.83K)
Cached input	137,984 (137.98K)
Cache writes	0
Output tokens	270
Total tokens	139,099 (139.1K)
Codex credit rate	input 125 · cached 12.5 · output 750 cr / 1M tokens
API Standard rate	input $5 · cached $0.50 · cache write $6.25 · output $30 / 1M tokens
Estimated Codex cost	~2.03 cr
API-equivalent cost	~$0.08
Effective blended usage	68,423 (68.42K) tokens / cr
Local Python process	0 model tokens · 0 cr · $0.00 API usage

Values above are illustrative snapshots. Your model, rates, and usage will differ.

Installation

Requirements

• The ChatGPT desktop app with Codex plugin support
• Codex CLI with plugin commands, if you want to install or run it from a terminal
• Python 3.9 or newer
• Local access to Codex rollout files
• No third-party Python packages at runtime

Codex installs plugins from marketplace catalogs. This repository is the plugin package itself, so a local installation has two parts: clone the package and expose it through your personal marketplace.

1. Clone the plugin

Clone the repository into the common personal plugin directory:

mkdir -p ~/.codex/plugins
git clone https://github.com/razzededge/codex-usage-audit.git \
  ~/.codex/plugins/codex-usage-audit

On Windows, use the equivalent directories under %USERPROFILE%.

2. Add it to the personal marketplace

Create ~/.agents/plugins/marketplace.json if it does not exist. If it already exists, merge the plugin entry into its existing plugins array instead of replacing the file.

{
  "name": "personal",
  "interface": {
    "displayName": "Personal"
  },
  "plugins": [
    {
      "name": "codex-usage-audit",
      "source": {
        "source": "local",
        "path": "./.codex/plugins/codex-usage-audit"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

This example uses the common personal layout at ~/.codex/plugins/. Other locations work when source.path is adjusted; paths are resolved relative to the personal marketplace root, not the directory containing marketplace.json.

3. Install the plugin

ChatGPT desktop app

Restart the ChatGPT desktop app, open Codex → Plugins, choose the Personal marketplace, and install Codex Usage Audit. Start a new task so the installed skill and hook are loaded.

Non-managed command hooks require trust. Open /hooks, review the bundled Stop hook, and trust it only when the command matches this repository.

Codex CLI

If your Codex CLI exposes the plugin commands, install and confirm the plugin with:

codex plugin add codex-usage-audit@personal
codex plugin list

Then start a new Codex task and review the hook as described above.

Updating

Pull a newer release and reinstall it from the same marketplace:

git -C ~/.codex/plugins/codex-usage-audit pull --ff-only
codex plugin add codex-usage-audit@personal

Start a new task after an update. Published releases should change the version in .codex-plugin/plugin.json so Codex creates a fresh installed snapshot.

Publishing through a Git marketplace

For one-command Git distribution, place this package at plugins/codex-usage-audit/ inside a marketplace repository and add .agents/plugins/marketplace.json at that repository's root. Consumers can then run:

codex plugin marketplace add OWNER/MARKETPLACE_REPOSITORY --ref main
codex plugin marketplace list
codex plugin add codex-usage-audit@MARKETPLACE_NAME

See the official Codex plugin documentation for marketplace packaging and distribution.

Usage

From Codex

Invoke the bundled skill explicitly:

Use $codex-usage-audit:usage-report to show token usage, estimated costs,
rates, and overhead of this report command.

Codex can also select the skill implicitly when you ask about conversation usage, context pressure, cache efficiency, estimated credits, or whether to continue the current task.

From the command line

Run against the current Codex task when CODEX_THREAD_ID is available:

python3 skills/usage-report/scripts/usage_report.py --format markdown

Select another task by thread ID or absolute rollout path:

python3 skills/usage-report/scripts/usage_report.py \
  --session THREAD_ID \
  --format markdown

Available output formats:

# Full human-readable report
python3 skills/usage-report/scripts/usage_report.py --format markdown

# Compact report used by the Stop hook
python3 skills/usage-report/scripts/usage_report.py --format compact

# Raw numeric values for automation
python3 skills/usage-report/scripts/usage_report.py --format json

Exclude descendant subagents when needed:

python3 skills/usage-report/scripts/usage_report.py \
  --no-subagents \
  --format markdown

Use --help for the complete CLI reference.

Automatic per-turn report

The plugin bundles a Stop hook in hooks/hooks.json. When enabled and trusted, it runs the reporter after a Codex turn stops and displays a compact local summary. The hook can recover the newest available installed reporter snapshot when an older plugin cache directory has already been pruned during an update.

The hook process itself is local Python and consumes no model tokens, Codex credits, or API usage. See the official Codex hooks documentation for hook discovery and trust behavior.

How the metrics work

Scopes

Scope	Definition
Conversation	Selected parent task plus every locally discovered descendant subagent rollout
Current task	Selected parent turn_id plus descendant subagents spawned during that turn

Copied parent prefixes inside subagent rollouts are excluded to avoid double-counting.

Tokens and cache

• input_tokens, cached_input_tokens, cache_write_input_tokens, output_tokens, and reasoning_output_tokens come from local event_msg.token_count records.
• Repeated cumulative events are converted to positive deltas.
• Cached input is a subset of input and is never added twice.
• Cache writes are also a subset of input. They are never added to the displayed total a second time.
• Displayed total tokens are input + output.
• Reasoning output is displayed separately but remains part of output for cost calculation.
• Cache ratio is cached input / input.

Context pressure

Maximum context usage is the largest observed:

last request input tokens / model context window

It is request pressure, not the cumulative token total for the conversation.

Cost estimates

Codex-credit estimate:

(input - cached) × input_credit_rate / 1M
+ cached × cached_credit_rate / 1M
+ output × output_credit_rate / 1M

API Standard equivalent:

(input - cached) × API_input_price / 1M
+ cached × API_cached_price / 1M
+ min(cache_write, input - cached)
  × (API_cache_write_multiplier - 1)
  × API_input_price / 1M
+ output × API_output_price / 1M

The last term is only the premium above normal uncached-input pricing. For GPT-5.6, the bundled multiplier is 1.25, so cache writes receive the published 1.25× rate without being counted as a second set of input tokens. Models before GPT-5.6 default to a multiplier of 1.0.

Codex Fast multipliers apply only to the Codex-credit estimate. They are deliberately not reused for the API comparison because Codex Fast and API processing tiers are separate pricing systems.

Codex-credit estimates continue to treat cache writes as non-cached input. The published Codex rate card currently lists input, cached-input, and output credit rates, but no separate cache-write credit rate.

The bundled rate card records its retrieval date and sources:

• Codex rate card
• OpenAI API pricing
• OpenAI prompt caching

Recommendation

The report emits one deterministic workflow recommendation:

Recommendation	Typical signal
continue	Context pressure and task breadth remain below local thresholds
summarize	Context pressure, conversation length, or tool breadth is becoming material
start fresh	The latest parent context is at least 85% full
split	The task contains many tool calls or parallel work streams

The exact rules live in skills/usage-report/references/metrics.md.

Usage Report command cost

Codex writes a tool call before executing it and appends that model round's exact token event after the tool returns. The bottom section therefore has three possible states:

State	Meaning
pending	The reporter is currently running; exact telemetry is not in JSONL yet
complete	The next token event was associated with the model round that invoked the reporter
not_observed	No direct usage_report.py invocation was found in the selected task

The report never substitutes a previous round when the current value is pending. The automatic Stop report can show the completed value after the task finishes.

Command cost measures the whole model round that invoked usage_report.py. A later round that reads the tool result or writes a final response is not included. If the model round issued multiple tools, the report marks the cost as shared rather than attributing all of it exclusively to Usage Report.

Effective tokens / credit is the observed blended token-to-credit ratio for that round. It is not a monetary value for one credit.

Performance and local cache

Large conversations can span multiple parent and subagent rollout files. To avoid reparsing unchanged JSONL on every turn, the reporter:

1. Indexes rollout IDs once per report for constant-time descendant lookup.
2. Fingerprints each rollout by device, inode, size, and nanosecond modification time.
3. Reuses a serialized aggregate only when that fingerprint is unchanged.

Aggregate cache files live at:

~/.codex/usage-audit/rollout-cache-v1/

The cache directory is restricted to mode 0700 and files to 0600 on platforms that support POSIX permissions. The reporter rejects symlinked cache directories, permissive or oversized cache files, invalid schemas, and stale fingerprints. Cache writes use a temporary file followed by an atomic replace.

The cache contains only the aggregate structures needed by the report. Ignored transcript messages, prompt text, tool arguments, and tool output are not persisted. If the cache cannot be created or validated, the reporter safely falls back to parsing the rollout again.

It is safe to delete this directory; Codex Usage Audit will rebuild it from local rollout files.

Rate-card configuration

The reporter resolves its rate card in this order:

1. --rate-card PATH
2. CODEX_USAGE_RATE_CARD
3. $PLUGIN_DATA/rate-card.json when invoked by the plugin hook
4. ~/.codex/usage-audit/rate-card.json
5. Bundled skills/usage-report/references/rate-card.json

A minimal override looks like this:

{
  "name": "Example local rate card",
  "unit": "credits_per_million_tokens",
  "retrieved_at": "2026-07-22",
  "models": {
    "gpt-example": {
      "input": 100,
      "cached_input": 10,
      "output": 600
    }
  },
  "api_pricing": {
    "currency": "USD",
    "unit": "usd_per_million_tokens",
    "pricing_mode": "standard_short_context",
    "models": {
      "gpt-example": {
        "input": 4,
        "cached_input": 0.4,
        "cache_write_input_multiplier": 1.25,
        "output": 24
      }
    }
  },
  "fast_multipliers": {
    "gpt-example": 2.5
  }
}

Unknown models remain unpriced and make only the affected estimate partial. Update local rates when official pricing changes.

Privacy and security

Codex Usage Audit is designed to minimize data exposure:

• Reads local Codex JSONL rollouts only.
• Writes only a private, invalidation-aware aggregate cache under ~/.codex/usage-audit/rollout-cache-v1.
• Does not make runtime network requests.
• Does not emit prompts, assistant messages, tool arguments, tool output, or file contents.
• Detects direct reporter execution from a narrow usage_report.py --format/--hook sentinel and discards the remaining tool arguments.
• Text reports emit aggregates, model identifiers, report status, and local warnings.
• JSON reports additionally include the selected session and turn IDs, unavailable descendant session IDs, ordering timestamps, and the absolute path of the resolved local rate card.
• Keeps raw JSON output numeric; human-readable abbreviations exist only in text formats.
• Runs the automatic report as a non-blocking Stop hook.

Review hooks/hooks.json before trusting it. The command should execute only the bundled reporter through Python.

Project structure

codex-usage-audit/
├── .gitignore
├── .codex-plugin/
│   └── plugin.json
├── LICENSE
├── hooks/
│   └── hooks.json
├── skills/
│   └── usage-report/
│       ├── SKILL.md
│       ├── agents/openai.yaml
│       ├── references/
│       │   ├── metrics.md
│       │   └── rate-card.json
│       └── scripts/
│           ├── usage_report.py
│           └── test_usage_report.py
└── README.md

Development

Run the test suite:

python3 skills/usage-report/scripts/test_usage_report.py -v

Compile-check the Python files:

python3 -m py_compile \
  skills/usage-report/scripts/usage_report.py \
  skills/usage-report/scripts/test_usage_report.py

Validate JSON files:

python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m json.tool hooks/hooks.json >/dev/null
python3 -m json.tool skills/usage-report/references/rate-card.json >/dev/null

If the bundled Codex creator skills are installed, validate the skill and plugin package:

uv run --with pyyaml python \
  ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skills/usage-report

uv run --with pyyaml python \
  ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py .

These optional commands use uv to provide PyYAML to the creator validators. The plugin itself has no third-party runtime dependency.

Tests cover subagent prefix de-duplication, task/conversation scoping, token and cache math, GPT-5.6 cache-write premiums, Fast multipliers, independent API pricing, partial pricing, report-command detection, pending telemetry, hook behavior and version recovery, private aggregate caching, rollout indexing, formatting boundaries, malformed JSONL handling, and rate-card validation.

Limitations

• This is an unofficial community plugin and is not an OpenAI billing product.
• Local rollout telemetry cannot reproduce an official invoice.
• Authentication mode, delayed metering, missing descendant sessions, unknown models, or pricing-tier differences can change the result.
• An active report is a snapshot; the final response or an active subagent may be recorded later.
• Exact self-cost cannot appear inside the same tool execution because the token event is appended only after the tool returns.
• Transcript paths are useful local telemetry but may change in future Codex versions.
• The reporter requires CODEX_THREAD_ID or an explicit --session; it never guesses the globally newest task across open Codex windows.
• API-equivalent USD estimates use OpenAI's Standard, short-context list prices. For GPT-5.6, cache-write tokens are a subset of input tokens and receive the published 1.25× cache-write rate without being added again to total input.
• API-equivalent pricing excludes plan-included usage, taxes, long-context rates, Batch/Flex/Priority and regional processing, tool fees, negotiated rates, and later pricing changes.
• Codex credit estimates follow the published Codex rate card. Because that card currently has no separate cache-write credit column, cache writes remain part of non-cached input for the credit estimate.

Contributing

Issues and pull requests are welcome.

When contributing:

1. Keep the reporter local and privacy-preserving.
2. Never add fixture data copied from a real private transcript.
3. Add or update tests for behavior changes.
4. Preserve raw numeric values in JSON output.
5. Cite an official source and retrieval date when changing bundled rates.
6. Keep Codex-credit and API-equivalent calculations independent.
7. Run the full test and validation commands before opening a pull request.

License

MIT. See LICENSE.

Copyright (c) 2026 Damian Pieszczyński.

Codex and OpenAI are trademarks of OpenAI. This project is not affiliated with or endorsed by OpenAI.