Dashboard Guide

Unofficial project: Codex Usage Tracker is independent and is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI.

This local guide uses synthetic screenshots and does not contain prompts, assistant text, tool output, or real Codex session content.

Open The Dashboard

For the best experience, run the localhost dashboard server:

codex-usage-tracker setup
codex-usage-tracker update-pricing
codex-usage-tracker update-rate-card
codex-usage-tracker serve-dashboard --open

For optional allowance context, run codex-usage-tracker init-allowance or codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7" with current values copied from Codex Usage or /status.

To tune review thresholds locally, run codex-usage-tracker init-thresholds and edit ~/.codex-usage-tracker/thresholds.json. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.

To tune project attribution locally, run codex-usage-tracker init-projects and edit ~/.codex-usage-tracker/projects.json. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate cwd and local Git metadata when available.

Before sharing screenshots or generated artifacts, put --privacy-mode redacted or --privacy-mode strict before the subcommand, such as codex-usage-tracker --privacy-mode strict serve-dashboard --open. Redacted mode hides raw cwd/source paths, hides Git remote labels, and hashes unnamed projects while preserving configured aliases. Strict mode also hides project-relative cwd, Git branch, and tags. The dashboard header shows the active metadata mode.

The server enables live aggregate refresh and on-demand context loading. Static file mode can still filter, sort, and inspect aggregate fields, but cannot refresh logs or load context.

The localhost server uses a random per-server token for refresh and context API calls, validates loopback Host and Origin headers, and can run as aggregate-only with codex-usage-tracker serve-dashboard --no-context-api.

Insights View

The dashboard opens in Insights view. It ranks costly threads, Codex allowance usage, low cache reuse, context bloat, unpriced usage, estimated pricing, and reasoning-output spikes from aggregate fields only.

Needs Attention cards pair each signal with a next action.
Investigation Presets apply a view, derived filter, sort order, and explanatory caption together.
Presets include highest-cost threads, highest Codex credits, context bloat, cache misses, pricing gaps, and estimated-price review.

Calls View

Use Calls view to inspect individual model calls. Sort by attention, time, thread, model, tokens, cost, highest Codex credits, cache, context, or signals. Hover or click a row to pin grouped aggregate fields in Call Details. Top cards show cached input, uncached input, Codex credit usage, and optional usage remaining. The Time filter supports all time, today, this week, last 7 days, this month, and custom calendar ranges. Presets are relative to the browser's local date; custom ranges use inclusive start and end dates. The History control defaults to Active sessions only; switch to All history only when you want live refresh to scan archived session logs. The Confidence filter separates exact cost, estimated cost, unpriced cost, exact credit-rate matches, inferred credit mappings, user credit overrides, and missing credit rates. The URL tracks the active view, filters, time preset or custom range, history scope, sort, preset, selected row or thread, page, and expanded threads. Copy link copies that state, and Export CSV downloads the currently filtered aggregate calls. The header uses short status chips; exact refresh time and source details live in hover titles so live refreshes do not reflow the page. A Parser warnings chip appears only when the latest refresh reports skipped token events, missing expected token fields, invalid counters, duplicate cumulative snapshots, or unknown event shapes.

Last call total is the selected model call.
Session cumulative is the running total Codex logged for that session.
Cached input and Uncached input make cache behavior visible without storing transcript text.
A cost with * means the pricing row is a marked best-guess estimate.
Codex credits are estimated from aggregate input, cached-input, and output counters using bundled or locally configured rate-card values. Direct matches are exact, inferred mappings are estimated, and local credit-rate overrides are user-provided.
Search matches derived project names, project-relative cwd values, tags, branch names, and redacted remote labels.
Time values are shown in your browser's local date/time format while sorting and time filtering still use the logged timestamp.
In redacted or strict privacy mode, search only sees the redacted metadata fields included in the dashboard payload.
Usage Remaining is not read from the logged-in account plan. Configure ~/.codex-usage-tracker/allowance.json with values copied from Codex Settings > Usage, the Codex Usage dashboard, or /status when you want current remaining allowance context.
Call details include a recommended action and a "why flagged" explanation derived only from aggregate counters and pricing/allowance metadata.
Raw aggregate identifiers and source file metadata are collapsed until you need them.

Threads View

Use Threads view to understand a work session as a group. Expand a thread to see calls oldest to newest. Subagents with logged parent session ids are shown under their parent thread; inferred auto-review attachments are marked in the details panel. Selected threads also show lifecycle signals such as first expensive turn, largest cumulative jump, cache trend, context trend, and whether subagent or auto-review work appeared before a usage spike.

Details And Context

Details panel showing aggregate usage fields for a selected call.

The details panel shows primary cost, Codex credits, allowance impact, cache, context, pricing, and next-action signals first. It then groups thread narrative, token/pricing breakdowns, credit confidence and rate-card source metadata, collapsed raw identifiers, and source metadata. When served from localhost with the context API enabled, Load context fetches one redacted, size-limited source excerpt on demand. When started with --no-context-api, context buttons stay disabled and the dashboard remains aggregate-only.

Investigating Long Chat Growth

Prompt caching helps, but cached input is not free. Long-running chats can carry a large cached prefix into later turns, so usage can climb quickly even when the visible request looks small.

Watch Cached input, Uncached input, Session cumulative, Context use, and Cache ratio together. When old context is no longer useful, starting a fresh Codex thread may be more efficient than carrying a large cached history forward.

Privacy Model

The dashboard includes session ids, thread names, cwd values, source file paths, timestamps, model labels, reasoning effort, token counts, cost estimates, Codex credit estimates, optional manually entered allowance windows, and derived ratios. It does not include prompts, assistant responses, raw tool output, pasted secrets, message snippets, or transcript text. Remaining 5-hour and weekly allowance is not read from Codex logs or inferred from the logged-in account plan automatically. Local Codex logs may also omit usage from other ChatGPT agentic surfaces that share the same allowance. Archived sessions are excluded from dashboard payloads by default; All history is an explicit opt-in because archived logs can make refreshes slower and make current dashboards look inflated by older work.

Use --privacy-mode redacted or --privacy-mode strict before sharing generated dashboards, CSV exports, query JSON, or support bundles. Redacted mode removes raw cwd/source paths and hides unnamed project names behind stable hashes. Strict mode also hides project-relative cwd, branch, and tags. Configured project aliases are treated as explicit display opt-ins in both modes.

Pricing and Codex credit estimates are source-stamped local calculations. Use codex-usage-tracker pin-pricing --output <path> when a report needs to keep the same USD pricing snapshot over time, and use codex-usage-tracker update-rate-card when you want an explicit local copy of the bundled Codex credit rate-card snapshot.