Codex Token Usage Dashboard: Test Coverage Before Trust

Use the official Codex usage dashboard when the decision is “how much capacity do I have left?” Use /status for the active CLI session, and /usage for daily, weekly, or cumulative account token activity. Build or adopt a local dashboard only when you need a stronger claim: which expected task used the tokens, which model handled it, how fresh the evidence is, and how much account activity remains unattributed. Those surfaces are complementary. A limit percentage is not a task ledger. A live session counter is not a historical account total. A model breakdown is not complete merely because every observed row has a model; an expected task may be missing altogether. Before trusting a Codex token usage dashboard , make it pass four checks: freshness, task coverage, model coverage, and reconciliation to a broader total. Choose the surface by the decision OpenAI's current Codex documentation points to the usage dashboard for current limits. During an active CLI session, it points to /status for remaining limits. The current CLI guide gives three more useful distinctions: /status reports the active model, policy and workspace context, plus current token usage. /usage daily , /usage weekly , and /usage cumulative show account token activity for those views. /statusline can keep model, context statistics, rate limits, token counters, session identity, and project context visible in the terminal footer. The reasonable default is therefore smaller than a custom analytics project. If you only need to know whether another long task fits inside the current limit window, open the official dashboard. If you are deciding whether the current chat needs compaction, inspect /status or a configured status line. If you need an account trend, use /usage . Do not silently extend those documented contracts. The fact that a surface shows a token number does not prove that it retains every task, exposes a model for every row, or reconciles to another total. Record what a source actually promises, then mark every unsupported field unavailable. For larger workspaces, OpenAI documents a Codex Analytics API for programmatic, aggregated usage and activity reporting. The same page says it is not a raw audit log interface. That boundary matters: aggregated workspace reporting can answer adoption and trend questions without automatically becoming evidence for a particular task, retry, or deliverable. Decision Smallest suitable surface Claim it can support Can I start another large task? Official usage dashboard Current limit and capacity planning Is this active chat consuming context? /status or /statusline Current session context and token state What is my account token trend? /usage Daily, weekly, or cumulative account activity What is happening across a workspace? Analytics API, when available Aggregated workspace usage and activity Which task and model explain the total? Coverage audited local ledger Task attribution, model coverage, and reconciliation within its proven scope A third party local tracker can be a valid fifth option, but its feature list is not the acceptance test. Inspect the source of its data, the Codex versions it supports, whether it reads locally or uploads records, how it handles deleted or compacted sessions, and what happens when the parser sees an unknown schema. A dashboard that fails closed with unknown is more useful than one that keeps drawing a complete looking chart from partial records. Require four fields before calling a breakdown complete Start with an expected task manifest. If the dashboard begins from the usage rows it happened to discover, it cannot distinguish “no tokens used” from “task missing from ingestion.” The manifest can be simple: The four checks operate on different failure modes. Freshness asks whether the evidence is recent enough for the decision. Store observed at , the source, and the collection window. A limit snapshot from yesterday may be harmless in a monthly report and dangerous before starting a long task. Set the maximum age beside the consumer rather than declaring one universal threshold. Task coverage divides expected tasks with usage evidence by all expected tasks. It must start from the manifest, not the discovered rows. Four rows with usage out of four observed rows can still mean 80% coverage if a fifth expected task never appeared. Model coverage divides attributed usage rows with a resolved model by all attributed usage rows. Keep null when the model is unavailable. Grouping an unknown model under whichever model is configured now would rewrite historical evidence. Reconciliation compares task attributed tokens with a broader total for the same identity and time window: This difference is a diagnostic, not an accusation. It can represent a missing task, a retry without stable identity, a time window mismatch, a source that updates later, or activity outside the local collector. Negative differences deserve equal suspicion: they can indicate duplicate ingestion, overlapping windows, or incompatible token definitions. Keep the scopes visible: Never reconcile a current session context counter to an account daily total merely because both are expressed in tokens. Confirm that identity, time window, token classes, retries, and source semantics are compatible. If they are not, show both numbers separately. Replay a dashboard that looks current but is incomplete The accompanying fixture is synthetic. It contains four expected Codex tasks and an account daily total. Every timestamp is within a deliberately strict 30 minute freshness policy. Three tasks have usage records; two of those have a model; three tasks have a verified outcome. The account surface reports 18,200 tokens, while task rows explain 13,600. Run the audit: The deterministic result is: The important finding is not the 18,200 token total. It is that freshness and completeness disagree. All collected sources are fresh, yet one expected task has no usage record, one attributed task has no model, one task has no verified outcome, and 4,600 account tokens are unexplained. A polished chart could hide every one of those conditions. The fixture uses a 5% unreconciled threshold to make the failure obvious. That is a test policy, not a universal Codex recommendation. A personal trend chart may tolerate a wider difference. A team chargeback, optimization experiment, or budget alarm should require tighter identity and window alignment. Put the threshold, its owner, and its rationale in configuration. This audit also refuses a common shortcut: using outcome success to fill missing token evidence. The fourth task has a verified outcome but no usage row. Its work may have succeeded, but its consumption is still unknown. Conversely, the third task has token evidence but an unverified outcome. Consumption occurred; useful completion remains unproven. Select a dashboard with failure tests, not screenshots Test a candidate dashboard with a small controlled run before adopting it. Create two short tasks and one task that retries. Record the expected task IDs, chosen models, start and end times, and a deterministic outcome check. Then ask: 1. Does each expected task appear exactly once, while retry attempts remain separately identifiable? 2. Does every attributed row preserve its model, source, timestamp, and token classes? 3. Can the tool expose the raw evidence behind an aggregate without exposing prompts, tool payloads, secrets, or absolute paths? 4. Does the task sum reconcile to a compatible account or workspace total for the same window? 5. When you introduce an unknown record shape, does the collector mark it unsupported instead of dropping it silently? 6. After a Codex upgrade, does the parser report its tested version range and fail visibly on drift? These tests are more valuable than a long feature matrix. Model pie charts, leaderboards, and cost projections become misleading when the denominator is incomplete. A local tool that reports coverage: 72% and unreconciled: 18% is operationally stronger than a richer dashboard that reports neither. Privacy is part of correctness. Token analysis normally needs identifiers, timestamps, model names, token classes, and outcome references. It usually does not need prompt bodies, assistant responses, tool arguments, secrets, or full filesystem paths. Hash or replace task identifiers when the readable name is unnecessary. Keep raw session data local where possible, and document any upload boundary before enabling it. Version drift deserves a first class status. Record collector version, Codex version, parser schema, last successful ingestion time, files or sessions scanned, unsupported records, and skipped records. “Last refreshed two minutes ago” is not enough if the collector skipped half the new format. Keep token evidence subordinate to the result A reconciled dashboard can support capacity planning, anomaly investigation, and before and after optimization. It still cannot prove that Codex made the requested code change, ran the right tests, preserved an approval boundary, or delivered the expected artifact. Join each task row to the cheapest deterministic outcome receipt available: a commit and diff, a test result, a generated file hash, a review verdict, or an external destination check. Then compare tokens per verified outcome, not tokens per process exit. A low token failed task is not efficient. A higher token task that resolves the issue may be the better operating result. The practical sequence is: 1. Use the official surface that already answers the immediate limit or account question. 2. Add a local task ledger only when the decision truly requires attribution. 3. Measure freshness, task coverage, model coverage, and unreconciled usage before trusting breakdowns. 4. Preserve unknown values and parser failures instead of manufacturing zeros. 5. Join consumption to a verified outcome before drawing an optimization conclusion. Sidewisp is currently in private preview. Token usage and estimated cost analytics are planned, not shipped. The product direction is to connect cost and context signals to useful progress and verified outcomes while showing evidence freshness and uncertainty. If that health boundary matches the way you operate agents, you can join the private preview. Sources OpenAI Codex pricing: current usage limits OpenAI Codex developer commands: /status , /usage , and /statusline OpenAI Codex Analytics API OpenAI Codex open source repository Codex Usage Tracker repository