Codex Usage Tracker 0.28.0

Feature-free stabilization and pre-1.0 contract freeze.

• Freezes the six-tool MCP, versioned HTTP/SSE, primary CLI, logical evidence, cache lifecycle, calculation-grade, four-token-class, JSON export, privacy, installation, and upgrade contracts.
• Qualifies fault recovery, scale, concurrent reads, rollback, and direct upgrades from public 0.26.0 and 0.27.0.
• Keeps optional context composition experimental and the overlay as a read-only contract without a shipped runtime.

Publication is performed only by the protected build-once Trusted Publishing workflow.

v0.27.0

Codex Usage Tracker 0.27.0 ships the lean product kernel guided-exploration release.

• Adds bounded, schema-driven guided data exploration.
• Keeps optional context composition isolated, owner-only, and disabled by default.
• Freezes the read-only overlay adapter boundary without shipping overlay assets.
• Strengthens protected publication with merged-main tag fencing and exact sdist source-byte checks.
• Preserves the six-tool MCP surface and fast incremental kernel workflows.

Codex Usage Tracker 0.26.0

Codex Usage Tracker 0.26.0 replaces the beta analysis and compatibility product with a lean local data kernel built for exact, incremental, model-driven exploration.

Highlights:

• Exact incremental facts with explicit refresh, atomic generation promotion, and preserved rollback metadata.
• Six focused MCP tools, ten operational CLI commands, and seven kernel HTTP routes.
• A focused Evidence Console with bounded queries, exact timelines, live reconnect, and no implicit refresh.
• Side-by-side cache cutover that leaves the 0.25 cache untouched.
• Removal of narrative analysis jobs, OTel, telemetry, compression, diagnostics, recommendations, content indexing, compatibility profiles, and legacy dashboard assets.
• Protected build-once promotion through TestPyPI, PyPI, and GitHub Release assets.

See CHANGELOG.md and the Product Kernel Reset roadmap for the complete contract and migration details.

Codex Usage Tracker 0.25.1

Release 0.25.1

Release 0.25.1 removes the experimental local telemetry sidecar and hardens the
incremental refresh lifecycle used by the seven-tool MCP surface.

Refresh reliability

• Stale analysis reuses an already-running compatible refresh, including while
  append-active JSONL source revisions continue moving.
• Job polling derives outer status and detailed progress from one durable row,
  preventing mixed running/failed snapshots.
• Detached refresh startup returns the durable post-handshake state instead of
  a stale queued snapshot.
• Completed refresh and analysis results remain available after an MCP restart.
• Refresh remains incremental after the initial index build and preserves
  concurrent reads from the last committed generation.
• Append-safe allowance and thread-link maintenance updates only the moving
  tail. Schema 38 removes low-selectivity revision indexes, and reset-aware
  model v5 extends the deterministic source revision for new observations.
• execution="auto" routes large-history analysis through a durable
  asynchronous job instead of blocking one MCP request on the full analysis.

Telemetry sunset

• The telemetry parser, exporter cursor, staging tables, reconciliation pass,
  refresh phase, diagnostics, and support-bundle fields are removed.
• Schema 38 drops retired staging tables in place without rebuilding canonical
  usage rows.
• Shared service_tier, fast, pricing, export, and Evidence Console fields
  remain because live product surfaces still use them.

The core MCP catalog remains exactly seven tools. No legacy telemetry runtime,
compatibility flag, or fallback path is retained.

Qualification

• The full Python suite passed with 2,058 tests and 88.07% coverage. Ruff,
  MyPy, configured Pyright, Tach, release-readiness, and product-complexity
  checks passed.
• All 599 frontend tests, lint, typecheck, dependency, dead-code, style,
  source-governance, deterministic-asset, and bundle gates passed.
• All 14 Chromium release-candidate tests passed, including Home startup
  without hidden heavy analysis.
• The 100,000-row synthetic gate completed a 45-row append in 1.416816s, a
  one-row moving-tail refresh in 1.027582s, a no-change refresh in
  0.003999s, and a concurrent committed read in 0.003857s.
• At 216,000 rows, post-build work remained bounded: 3.871973s for 45
  appended rows, 2.290849s for one moving-tail row, 0.004112s for no
  changes, and 0.006584s for a concurrent committed read. The one-time cold
  build was 54.356171s.
• Clean installed-wheel probes exposed exactly seven tools and completed 39–40
  MCP calls across two independent tasks. They hydrated a moving tail, preserved
  completed refresh and analysis results across restart, and reused the
  durable repeated-analysis result.
• Five consecutive clean installed-wheel stress runs passed after the startup
  state contract was tightened. The maximum server-reported MCP call time was
  604.045ms.

Codex Usage Tracker 0.25.0

Highlights

Codex Usage Tracker 0.25.0 makes the MCP/plugin and live Evidence Console the dependable central product.

• MCP and Evidence Console startup is read-only against the committed usage index. Equivalent refreshes from separate Codex tasks now join one durable cross-process job in the operational sidecar instead of competing for the usage database writer lock.
• Incremental refreshes capture a fixed newline-aligned source boundary, leave concurrent appends for one bounded follow-up, expose generation/tail/progress timing, and reuse compatible durable analysis results.
• Home now reads current call, token, and cache totals from compact summaries even while optional recommendation materialization catches up. The persisted Recent findings section and its load-path query are removed.
• The legacy static dashboard product is removed: static generator/assets, dashboard and open-dashboard aliases, MCP generate_usage_dashboard, and configured static serving. /dashboard.html returns a data-free 410 migration page for 0.25, while / redirects to /react-dashboard.html.
• CSV/JSON exports, Evidence Console deep links, React/locales, canonical accounting, privacy/raw-context controls, schema integrity, and focused Home/Limits/Calls/Threads/thread-call query plans remain supported.
• Release gates now fail closed on stale static-only JavaScript syntax globs, and package/plugin/runtime versions share one deterministic bundle identity.

Upgrade

pipx upgrade codex-usage-tracking
codex-usage-tracker setup --force-plugin

Then restart Codex so it loads the 0.25.0 plugin/MCP bundle. Reopening the browser against an already running service does not rebuild the index; use service serve --no-refresh when you want to serve the last committed generation while a separate refresh is running.

See the 0.25.0 release guide and upgrade guide.

codex-usage-tracker 0.24.0

Release 0.24.0 — Hardened Architecture and Delivery

Release 0.24.0 hardens the foundation beneath the MCP-first usage analyst and
Evidence Console. It preserves the focused user workflows introduced in 0.23
while making dependency direction, SQLite integrity, context retrieval,
long-running analysis, quality gates, and artifact promotion explicit and
fail-closed.

Stable Product Surface

The default MCP profile still exposes exactly 7 core tools. The full profile
exposes 59 full tools, and the developer profile exposes 64 developer tools.
Primary CLI help still contains 11 commands. Home, Explore, Limits, Settings,
and contextual Evidence remain the supported browser surface.

The SQLite store advances additively to schema version 37. Version 35 records
source byte offsets for bounded context reads; versions 36 and 37 persist
generic analysis jobs and safe lease recovery. Existing rows and public
accounting semantics remain intact.

Reliability and Performance

• Added an application composition root and explicit dependency protocols so
  CLI, HTTP, MCP, and background services can run from injected temporary paths
  without hidden global defaults.
• Removed Python dependency cycles and enabled the blocking Tach architecture
  policy with root_module = "forbid".
• Enabled SQLite foreign keys on normal connections, made migration failure
  atomic, proved retained historical upgrades, and hardened interrupted
  rebuild recovery.
• Added direct byte-offset context retrieval with byte-for-byte payload
  equivalence and a bounded sequential fallback for pre-v35 rows.
• Persisted reusable analysis jobs, results, progress, failures, and leases so
  interrupted work can recover across process restarts.
• Kept the focused Home, Limits, Calls, Threads, and thread-call routes that
  protect the 0.23 large-history latency and freshness gains.
• Made compression-status polling read-only and preserved the refresh
  deduplication index to avoid redundant SQLite work.

Release Integrity

Coverage, changed-line coverage, architecture, workflow action pins, package
contents, product complexity, bundle size, and release evidence now block CI
directly. The release workflow builds one wheel/sdist pair, qualifies the exact
bytes on TestPyPI, promotes those downloaded bytes to PyPI, and attaches the
PyPI bytes plus the same manifest and promotion evidence to the GitHub Release.

The canonical artifact manifest records the source commit, artifact SHA-256
digests, schema version, all JSON schemas, all MCP profile inventories, and
every packaged Evidence Console bundle digest. The
manifest example uses placeholder
digests to document the shape; the workflow artifact is the release evidence.

Compatibility

Investigator, Compression Lab, Cache and Context, Diagnostics, and Reports are
now localized, notice-only routes. Opening them does not load their historical
queries, start background jobs, or import retired page chunks.

CLI, HTTP API, CSV export, and full-profile MCP compatibility remain available
through 0.24.x. The notice pages provide replacement core requests and direct
paths to Evidence, Explore, and Limits. These compatibility surfaces are due
for removal in 0.25.0; there is no early removal in this release.

See Upgrading to 0.24.0 for operator steps and the
deprecations ledger for normative removal dates.

Release-Candidate Evidence

The release gate covers Python 3.10 through 3.14, the full Python and frontend
suites, 85% aggregate and 90% changed-line coverage floors, architecture and
integrity checks, dashboard browser contracts, 100,000-row route budgets,
context-offset performance, package complexity, wheel/sdist inspection, Twine,
and installed-package smoke tests.

The public artifact hashes and qualification results are recorded by the
Trusted Publishing workflow in release-manifest.json and
promotion-evidence.json; no local PyPI credentials or local publish step is
used.

codex-usage-tracker 0.23.0

Release 0.23.0 — Evidence Console

Release 0.23.0 completes the user-facing MCP-first pivot. Conversational MCP
analysis remains primary; the local Evidence Console is now the focused
verification surface for Home, Explore, Limits, Settings, and contextual
Evidence.

Stable Product Surface

Primary analytical navigation contains Home, Explore, and Limits. Settings is
a separate shell utility action. Evidence is contextual and accepts exact call,
thread, finding, and allowance selectors.

The CLI primary help now contains exactly 11 top-level commands:

setup status doctor refresh analyze query open export config service admin

status, bounded query, and analyze use the same v2 application contracts
as MCP and HTTP. open consumes codex-usage-tracker-dashboard-target-v2 or
an exact target selector. Historical CLI spellings remain accepted through
0.24.x and are hidden from primary help.

What Changed

• Replaced the old dashboard-first navigation with Home, unified Calls/Threads
  Explore, Limits, and a utility Settings action.
• Restored the four-card Usage Pulse, loading progress, scoped timeframe
  summaries, and a guided MCP/plugin prompt library on Home.
• Added focused Calls, Threads, and thread-call endpoints with exact filter,
  count, cost, credit, sorting, and pagination behavior; expanded thread calls
  use the same readable row model as Calls.
• Added one contextual Evidence route for call, thread, finding, and allowance
  verification with canonical return targets and recoverable stale-link states.
• Kept Investigate, Compression Lab, Cache and Context, Reports, and Diagnostics
  directly routable only during their documented transition window.
• Added eight bounded /api/v2/ routes for status, refresh, jobs, analysis,
  query, evidence, allowance, and capabilities.
• Removed the experimental Usage Constellation and its Three.js dependencies
  and packaged assets.
• Simplified the CLI while retaining compatibility aliases and the v1 query
  path for old-only filters and --limit 0.
• Changed service serve --refresh to bind and serve the stored snapshot first,
  then run the full refresh in the background. Batched canonical fingerprint
  classification removes one SQLite lookup per ingested row.

Compatibility

Old stable URLs normalize to their current destination. Existing v1 HTTP
routes, static dashboard commands, legacy workbenches, full-profile MCP tools,
and historical CLI aliases remain available through the compatibility window.
No manual database step is required. Startup applies schema migrations 32–34,
which add allowance-history, focused recommendation/call sorting, source, and
parent-thread lookup indexes without rewriting stored usage rows.

See Evidence Console Route Migration
for exact URL mappings and Upgrading to 0.23.0 for
operator steps.

Release-Candidate Evidence

The final local candidate has 15 browser routes: five Evidence Console routes
(three primary, one contextual, and one utility) plus ten direct-only legacy
routes. Explore contains Calls and Threads modes. The MCP profiles expose 7
core, 59 full, and 64 developer tools; the CLI exposes 11 primary commands and
keeps 34 hidden compatibility aliases. The shared JSON inventory contains 95
schemas.

The candidate passes 1,905 Python tests at 88% coverage, 609 frontend tests,
and 14 Playwright release-candidate scenarios. The required 100,000-row
dashboard route budget passes with Calls at 0.074 seconds p95, Threads at 0.007
seconds p95, and thread calls at 0.014 seconds p95. Initial dashboard payloads are
60.02 KiB JavaScript and 9.66 KiB CSS; the largest visualization chunk is the
documented 112.00 KiB gzip ADR exception below its 113.00 KiB limit. Exact
package, responsive-browser, and performance evidence is recorded in the
pivot execution ledger.

All screenshots use the repository's synthetic eight-call fixture and contain
no real Codex logs, prompts, assistant text, tool output, or private paths.

The public artifacts are built and published only by the repository's GitHub
Actions Trusted Publishing workflow.

Contributor Credit

Thanks to @nrlcode for
PR #291,
which independently identified the dropped canonical-fingerprint index as the
full-refresh deduplication bottleneck and contributed reproducible 10,000-row
and 100,000-row benchmark evidence plus a focused regression-test design.
Release 0.23.0 ships the batched fingerprint lookup implementation developed
for the same root cause, so the overlapping patch itself is not duplicated.

codex-usage-tracker 0.21.0

What’s new

• Keep the macOS dashboard available at a stable, localhost-only URL with a login LaunchAgent, explicit port-collision handling, health checks, and install, status, and uninstall commands.
• Preserve responsive inline thread expansion while bounding initial work and polishing progressive call loading, retry behavior, and row presentation.
• Preserve full-width Windows filesystem identifiers so distinct sources do not collapse during aggregate usage ingestion.
• Ingest aggregate response.completed telemetry from local codex-completions*.jsonl exporter files and conservatively reconcile exact Fast/Standard service-tier evidence without retaining raw response bodies or arbitrary OTLP attributes.
• Show exact service tier separately from the existing Fast proxy in Calls, details, and CSV exports; older or unmatched history remains Unknown.
• Apply documented model-family Fast multipliers to confirmed Codex credit estimates with source metadata and local overrides while leaving standard-credit allowance calibration unchanged.
• Cache Standard, Batch, Flex, and Priority API pricing together, select the observed tier per call, and expose Standard/Priority cost scenarios without applying ChatGPT Fast multipliers to API USD estimates.
• Preserve exact response tiers in dashboard labels and CSV contracts, clear OTel staging on confirmed database reset, and make incremental source cursors safe across concurrent file rotation and same-inode rewrites.

Verification

• Full 1,114-test suite passed locally and across Python 3.10–3.14 in CI.
• Package build, metadata, release-readiness, security, dashboard quality, and installed-wheel smoke checks passed.

Full details are in the changelog.

codex-usage-tracker 0.20.0

What's Changed

• fix: apply GPT-5.6 long-context pricing by @maopai in #271
• fix: improve dashboard visualization layout by @maopai in #272
• feat: complete Simplified Chinese localization by @maopai in #274
• feat: expand thread calls inline by @douglasmonsky in #276
• chore: prepare 0.20.0 release by @douglasmonsky in #277

New Contributors

• @maopai made their first contribution in #271

Full Changelog: v0.19.0...v0.20.0

codex-usage-tracker 0.19.0

What's Changed

• feat: add canonical usage deduplication and limits intelligence by @douglasmonsky in #273
• chore: prepare 0.19.0 release by @douglasmonsky in #275

Full Changelog: v0.18.0...v0.19.0