CodexUsageCenter

简体中文 · English

CodexUsageCenter is a Windows 11 desktop application for inspecting local Codex usage. It incrementally indexes Codex JSONL session logs, presents Token and cache trends, and estimates cost from a user-controlled price book. The application does not call the OpenAI billing API and does not treat its estimates as an invoice.

Cost is reconstructed from local logs and current prices. It can differ from an official bill because logs may be incomplete, historical prices may have changed, and plans, credits, discounts, tax, or billing-side rounding are not represented.

Why this project

• Local-first analysis. Prompt text, response text, and tool payloads are not copied into the usage database.
• Incremental indexing. Per-file byte cursors avoid repeatedly parsing a large Codex history.
• Precise Token accounting. Token values use checked ulong arithmetic and an eight-byte big-endian SQLite BLOB representation across the complete UInt64 range.
• Editable cost model. Prices are stored per model for fresh input, cache reads, cache writes, and output. Unknown prices remain unknown rather than being treated as zero.
• USD by default. Manual exchange rates and cached ECB daily reference rates are available for non-USD display.
• Reusable Windows glass. The repository contains LiquidGlass.WinUI3, an independently buildable WinUI 3 component used by every dashboard surface.

Application

The interface contains four working pages:

1. Overview — usage-event KPIs, Token totals, estimated cost, trends, model distribution, recent calls, and recent records.
2. Requests — date, model, and session filters with detail views and pagination.
3. Tokens — input, cache, output, and reasoning trends with model comparisons.
4. Settings — log locations, synchronization state, prices, exchange rates, theme, glass quality, frame-rate policy, and data management.

The top-level window retains the native Windows caption buttons, Snap Layout, keyboard behavior, DPI scaling, light/dark/system themes, and high-contrast resources.

Data flow

flowchart LR
    A["Codex JSONL logs"] --> B["Incremental parser"]
    B --> C["Stable event-key deduplication"]
    C --> D["SQLite events and hourly model rollups"]
    D --> E["Asynchronous dashboard queries"]
    F["models.dev price catalog"] --> G["Detected-model price cache"]
    H["ECB daily rates"] --> I["24-hour exchange-rate cache"]
    G --> E
    I --> E

Loading

By default, the importer reads:

%USERPROFILE%\.codex\sessions\YYYY\MM\DD\*.jsonl
%USERPROFILE%\.codex\archived_sessions\*.jsonl

It recognizes session_meta, turn_context, and event_msg/token_count, including cumulative total_token_usage and per-event last_token_usage. Stable event keys and database constraints deduplicate repeated scans, forks, and active-session moves into the archive. An incomplete final JSONL line remains pending until more bytes arrive.

Only usage events that can be associated with valid session metadata are counted. The displayed event count is therefore not an HTTP request count, billing request count, session count, or turn count.

Accounting model

Reasoning Tokens are a subset of output Tokens and are not added twice.

Metric	Definition
Fresh input	max(input total - cache read - cache write, 0)
Real consumption	input total + output
Cache hit rate	cache read / input total; unavailable when input is zero
Estimated cost	(fresh × input price + cache read × cache-read price + cache write × cache-write price + output × output price) / 1,000,000
Estimated cache saving	max(all input at regular input price - actual input-side estimate, 0)

All Token fields use System.UInt64. Arithmetic runs in checked contexts; an overflow aborts the current import transaction instead of wrapping. SQLite INTEGER cannot represent the full unsigned range, so Token values are stored as fixed-length, eight-byte, big-endian BLOBs with length constraints. Money, prices, and exchange rates use decimal.

Derived cost is not persisted with an event. Editing a price or exchange rate therefore re-estimates historical data immediately.

Prices and exchange rates

• USD is the default display currency.
• At startup, the application requests the public models.dev catalog once and retains prices only for models already detected in the local index.
• A manually edited model price takes precedence over synchronized data.
• If models.dev omits a cache-read or cache-write price, the application uses the regular input price for that field rather than assuming free Tokens.
• Network timeouts are eight seconds. A failed refresh keeps the last matching cache when one exists.
• Manual rates mean 1 USD = X target currency.
• Automatic non-USD conversion uses ECB daily reference rates through EUR and caches the result for 24 hours.
• Displaying USD does not require an ECB request.

models.dev is community-maintained. Neither synchronized prices nor the resulting estimates are guaranteed to match OpenAI billing.

LiquidGlass.WinUI3

CodexUsageCenter uses one LiquidGlassHost for the complete window. Cards, dense data panels, filters, buttons, tooltips, and the moving navigation lens register as Card, Dense, or Pill surfaces.

The current production renderer stays within DWM and Windows Composition:

DWM HostBackdrop
  → CompositionBackdropBrush
  → per-surface GaussianBlurEffect
  → rounded clipping, tint, rim highlight, inner/outer shadow, interaction
  → normal XAML content

This backend does not read HostBackdrop or desktop pixels into application memory. It also does not claim per-pixel HLSL displacement or independent RGB channel refraction for the production Composition path. HLSL and Direct3D 11 code retained in the component is not selected automatically by LiquidGlassHost.

On the validated Windows build, ordinary desktop capture preserved the complete live window without a screenshot mode. That observation is a tested behavior, not a promise that every Windows, driver, remote-session, or capture combination will composite DWM backdrops identically. High-contrast mode preserves system colors, while Remote Desktop reports the live material as unavailable rather than silently changing rendering contracts.

See the component README and Chinese README for its public API, package layout, and lifecycle contract.

Privacy boundary

• Codex source logs are opened read-only and are never modified.
• The database excludes prompt text, response text, and tool-input bodies.
• Stored metadata includes timestamps, session/rollout identifiers, model names, Token values, source-file paths, file cursors, fingerprints, synchronization state, and compact error summaries.
• Source paths and diagnostics can reveal a Windows account name or directory layout. The application data directory should therefore be treated as private.
• Runtime network access is limited to one models.dev catalog request per startup and optional ECB reference-rate requests. Neither request contains local logs, Tokens, session identifiers, paths, or detected model names.
• No OpenAI API key is required.

With package identity, data is stored under the MSIX LocalState directory. Without package identity, the fallback is %LOCALAPPDATA%\CodexUsageCenter. Principal files are:

usage.db
settings.json
model-prices.json
models-dev-prices-cache.json
ecb-rates.json
diagnostics.log

Requirements

• Windows 11 22H2, build 22621 or later
• x64 or ARM64
• For source builds: .NET SDK 10.0.202 and Visual Studio 2026/Build Tools 18.x with the Windows App SDK workload

The application targets .NET 10 and Windows App SDK 2.3.1. The reusable glass component targets .NET 8 so it can be consumed by .NET 8–10 WinUI 3 applications.

Install

Download the assets from the latest GitHub Release.

• CodexUsageCenter-1.1.0-win-x64-portable.zip — extract and run CodexUsageCenter.exe; no certificate installation is required.
• CodexUsageCenter-1.1.0-win-arm64-portable.zip — ARM64 portable build.
• CodexUsageCenter-1.1.0-x64-arm64.msixbundle — signed bundle containing both architectures; trust the accompanying public certificate before installation.

Detailed certificate and installation steps are in INSTALL.md. Verify downloaded files against SHA256SUMS.txt.

Build

Open CodexUsageCenter.slnx in Visual Studio, select x64 or ARM64, and start the CodexUsageCenter project. From PowerShell:

dotnet restore .\CodexUsageCenter\CodexUsageCenter.csproj `
  -p:Platform=x64 `
  -p:RuntimeIdentifier=win-x64

dotnet build .\CodexUsageCenter\CodexUsageCenter.csproj `
  -c Debug `
  -p:Platform=x64 `
  -p:RuntimeIdentifier=win-x64 `
  --no-restore

dotnet run --project .\CodexUsageCenter\CodexUsageCenter.csproj `
  -c Debug `
  -p:Platform=x64 `
  -p:RuntimeIdentifier=win-x64

The first restore requires NuGet access. dotnet run can require Windows Developer Mode for debug package-identity registration.

Test and validation

dotnet test .\CodexUsageCenter.Tests\CodexUsageCenter.Tests.csproj `
  -c Debug

dotnet test `
  .\components\LiquidGlass.WinUI3\tests\LiquidGlass.WinUI3.Tests\LiquidGlass.WinUI3.Tests.csproj `
  -c Debug `
  -p:Platform=x64 `
  -p:RuntimeIdentifier=win-x64

The v1.1.0 source was validated with:

• 93/93 application/domain/infrastructure tests passing;
• 55/55 component and shader-contract tests passing;
• x64 Debug and ARM64 Release builds completing with zero warnings and zero errors;
• a responsive x64 window using an active Composition renderer in an ordinary desktop screenshot.

ARM64 was built and package-structure checked on x64 Windows, but it was not launched on a physical ARM64 Windows device. Automated tests use synthetic JSONL data and do not prove compatibility with every future Codex log format or the performance of every multi-gigabyte history.

Repository layout

CodexUsageCenter.slnx
├─ CodexUsageCenter/                  WinUI 3 UI and ViewModels
├─ CodexUsageCenter.Domain/           Token, pricing, and settings models
├─ CodexUsageCenter.Application/      queries and application services
├─ CodexUsageCenter.Infrastructure/   JSONL, SQLite, pricing, and exchange rates
├─ CodexUsageCenter.Tests/            unit and integration tests
└─ components/LiquidGlass.WinUI3/     reusable glass component, Gallery, tests

Boundaries

• Only local Codex JSONL logs are indexed.
• OpenAI Usage/Billing APIs are not queried.
• Multi-device synchronization is not provided.
• Cost remains an estimate under the current user price book.
• Mid-file rewrites of already consumed JSONL regions require a manual index rebuild; ordinary append and archive moves are incremental.
• A rebuild commits per source file. If interrupted, running the rebuild again restores a complete index.

License

CodexUsageCenter and LiquidGlass.WinUI3 are available under the MIT License. Third-party software and data sources retain their own terms; see THIRD-PARTY-NOTICES.md and the component third-party notices.