Automatic token usage reports for every Codex Task and turn. See Task totals, turn deltas, observed models, reasoning effort, and subagent usage in a compact local report.
Quick start · Examples · User guide · How the numbers work · Troubleshooting
Inspect extra codex exec sessions by working directory, watch for changes in the foreground, or use the optional launcher to retain start/exit and usage receipts for ephemeral runs. Hooks notify at tool-return boundaries after an updated hook review and a new Task. Launcher attribution stays distinct from native child lineage; exec usage is separate from parent totals. Commands and coverage.
Trust the fixed publisher entry once in CLI codex → /hooks. Routine runtime
and CLI updates then retain the same native hook definitions and need no new
trust review. By default, a prompt can start a bounded background check at most
once every six hours. Only releases signed by this plugin's pinned publisher key
are activated. New Tasks use the update; existing Tasks retain their version.
The first hook in a new Task reports its verified runtime version.
This authorizes future signed program changes from the same publisher. New hook
events, a changed entry/key, or plugin/skill structure still require a normal
plugin update and review of changed hooks. Nothing edits Codex's trust records.
Use python3 scripts/publisher_updates.py status|on|off|update|rollback from the
installed plugin directory (choose one action). status reports the runtime
version; the Plugins page may still show the older installed package version.
Controls, verification and release process.
Hook trust reminders.
A long Task can include many turns, model switches, and child agents. A single session total does not explain the latest change. Codex Usage Reports keeps those scopes visible:
| Question | What the report shows |
|---|---|
| How much has this Task used? | The selected parent Task's observed cumulative tokens. |
| What changed this turn? | The native turn counter, or a valid difference between counters from the same source. |
| Which model and effort ran? | Settings observed in that turn, including visible changes. |
| Did subagents contribute? | A separate child subtotal and coverage status. |
| How much account quota remains? | Native quota observations when available, separate from Task tokens. |
| Can I inspect it later? | Local HTML, Markdown, and JSON receipts. |
The runtime uses Python's standard library. It does not call an LLM to calculate usage, require an API key, or send reports to a hosted analytics service. This is the standalone reporting extraction of Codex Run Budget.
Synthetic example rendered by the real report template in a standalone documentation frame. The desktop supplies its own surrounding theme.
繁體中文 example
Open the example gallery for downloadable HTML, a completed receipt, and the selected-Task report. Brand illustrations were created with Codex image generation; usage screenshots were rendered from synthetic fixtures. Artwork prompts.
Requires Python 3.10+ and a local Codex environment with plugin hooks. The inline card needs a desktop surface that supports local visualizations. CLI users can read the saved reports. Native state schemas are version-dependent; see compatibility and validation.
codex plugin marketplace add easyvibecoding/codex-usage-reports
codex plugin add codex-usage-reports@codex-usage-reportsReview and trust the plugin hooks in Codex, then start a new Task. Installed hooks are loaded according to the host's trust and lifecycle rules. See the official plugin guide and hook guide.
After an update that changes hook definitions, open /hooks in the Codex CLI and review changed plugin hooks again. Trust is bound to the exact hook definition: an installed and enabled plugin can still have modified hooks that Codex skips. Restarting the app or opening a Task from a phone does not grant trust. After completing the review, start a new Task.
Ask Codex to do your usual work. The hook records a turn baseline, asks for one pre-final card, and saves a receipt when a supported terminal event arrives. Reporting is enabled by default.
After Stop, one local Python worker checks for that turn's native task_complete record, with at most eight bounded scans and a 25-second retry deadline. It does not call a model or continue the Task. Once the completion boundary is observed, it saves a revised receipt that can include final-answer usage without counting the next turn. Missing or incomplete evidence stays pending or partial; disabling automatic reports also stops further reconciliation.
The inline card remains a snapshot taken before the final answer. Original Stop JSON, HTML, and Markdown receipts are preserved; a fresh Task-report query selects the latest published revision. Replacing the card's HTML file does not reliably refresh an existing card: in a phone remote A/B experiment, the original card kept version A after re-entering the Task, while a new reference displayed version B. Automatic replacement of existing inline cards is therefore not enabled. See reconciliation and preview behavior.
Use the bundled usage-report skill, for example:
Show the usage report for this Task, including turn totals and observed settings.
Or clone the repository for the standalone CLI:
git clone https://github.com/easyvibecoding/codex-usage-reports.git
cd codex-usage-reports
python3 plugins/codex-usage-reports/scripts/usage_reports.py auto-report status
python3 plugins/codex-usage-reports/scripts/usage_reports.py task "$TASK_ID" --format markdownSet TASK_ID to the native ID of the Task you want to inspect. The report stays scoped to that Task. See the full usage guide for exporting HTML, configuration, and uninstalling.
- Honest missing data. Counter resets, truncated records, and conflicting settings stay partial or unknown.
- Historical settings. Today's global model preference never replaces a past turn's observation.
- Completion checks. A bounded local worker reconciles later native records; original Stop JSON/HTML/Markdown receipts and inline snapshots are preserved.
- Separate scopes. Cached input is a subset of input; reasoning output is a subset of output. Child usage and account quota remain distinct.
- Local files. Native identifiers are hashed in report state. Private display names may appear in your local reports.
- Lightweight hooks. Reporting errors do not deny tools or stop the agent.
- Localized cards. English, Traditional Chinese, Simplified Chinese, Japanese, Korean, German, French, Spanish, and Portuguese; four README translations.
Both plugins are independent. If you keep the original for budget controls, disable its automatic report before enabling this one to avoid duplicate cards. No historical database migration is required. Migration instructions.
These are observed usage reports, not invoices or exact charges. Quota belongs to the account and cannot be allocated to a Task from token totals. Subagent attribution depends on available native lineage. Hook delivery and native schemas can change with Codex versions. The reporting plugin does not impose budgets or interrupt work.
Reports can reveal project names and usage patterns. Keep real reports local; use only synthetic fixtures in public issues. Privacy and security.
See CONTRIBUTING.md, architecture, and validation. Small reproducible bug reports and native-schema compatibility fixes are welcome. Please never attach a real transcript or database.
MIT © EasyVibeCoding contributors. Independent community project; not affiliated with or endorsed by OpenAI. Provenance.