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.

serve-dashboard refreshes active-session logs before opening by default. Use --no-refresh only when you intentionally want a cached view of the existing local index.

The server enables live aggregate refresh and on-demand turn-log evidence loading. Static file mode can still filter, sort, and inspect aggregate fields. open-dashboard refreshes before writing the snapshot unless you pass --no-refresh. Static files cannot refresh logs or load context after opening.

The localhost server uses a random per-server token for refresh and context API calls, validates loopback Host and Origin headers, and can start with context loading off through 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. Source pucks are call-level estimates derived from local event metadata: User means the token-count segment included a user message, Codex means it followed tool output, compaction, or agent-continuation metadata, and Unknown means the source event metadata was unavailable or ambiguous. Sort by attention, time, thread, model, tokens, cost, highest Codex credits, cache, context, or signals. Hover a row to scan a compact aggregate preview in Call Details; click a Calls row to open the dedicated call investigator. 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, expanded threads, and investigator record. 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 newest first by default, then click an expanded-call header to change the per-thread sort. 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.

Call Investigator

Clicking a Calls row opens dashboard.html?view=call&record=<record_id> for one model call. It separates exact callback counts, derived previous/next deltas, visible-context estimates, serialized local JSONL upper bounds, candidate serialized-overhead buckets, and redacted evidence loaded at runtime for the selected call. When the localhost context API is enabled, the investigator automatically loads a bounded turn-log evidence window with tool output included; use Hide tool output for a quieter evidence stream, and expand or load older surrounding evidence explicitly when needed. Visible evidence token estimates are calculated from the full selected-turn evidence set before display limiting, using tiktoken when available and a conservative character fallback only when the tokenizer is unavailable. The serialized upper bound tokenizes a redacted raw-JSON representation of the same selected-turn log slice. It can explain why visible text is much smaller than exact uncached input, but it can overcount because local JSONL includes client metadata that may not be prompt text. Bucket labels such as encrypted reasoning/state, local goal metadata, token callback metadata, and rate-limit metadata are counts only; raw text is not returned. encrypted_content is an opaque encrypted field found on some reasoning response items. The tracker cannot decrypt it and treats it as serialized state, not readable prompt, assistant, or tool text. Previous and next buttons move chronologically within the same resolved thread. Cache diagnostics label warm cache reuse, cold resume or stale cache, partial cache miss, uncached spike, and post-compaction without claiming exact cached text spans.

Details And Context

Calls view with a selected usage row and the compact Call Details rail collapsed.

The details rail is collapsed by default to preserve table space. Open Call Details when you want a compact aggregate preview without leaving the table. When expanded, it 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. The details panel still uses an explicit Show turn log evidence action so hovering rows does not pull raw context unexpectedly. Token-count context entries are labeled as the selected call, previous token count in the same turn, or earlier token count in the same turn when possible. Compaction events are shown as metadata first; compacted replacement history is transcript-like content and is returned only after an explicit Show compacted replacement action, with redaction still applied. Raw context is not written to SQLite, CSV, or generated dashboard HTML. When started with --no-context-api, context loading starts off; use Enable context loading in the details panel when you want to allow explicit row actions without restarting the dashboard server.

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.