Codex Usage Companion

Codex Usage Companion is a standalone VS Code dashboard for a durable local usage ledger and Task Storage. Each platform-specific VSIX includes the matching collector for macOS Apple Silicon or Windows x64; Python, uv, this repository, and the native app are not runtime requirements.

On activation, the extension authenticates an existing collector for the chosen CODEX_HOME or starts one parent-bound collector of its own. The collector is the only ledger writer, so stale descriptors and multiple VS Code windows do not create duplicate writers.

Install

1. In the VS Code Extensions view, search for Codex Usage Companion and choose Install.
2. Open the Command Palette and run Codex Usage: Set Up Collector. Choose CODEX_HOME, a capture interval (or Manual only), and migrate a compatible legacy cache if one is offered.
3. Run Codex Usage: Open Dashboard.

No source checkout, native app, or local copy of this repository is needed.

Supported Platforms

The extension ships separate platform VSIX packages for macOS 13 or later on Apple Silicon and Windows 10 or later on x64. Intel macOS, Windows ARM64, and Linux are not supported in 2.13.1.

What You Can Do

• Open the ledger-backed Usage dashboard without rescanning task JSONLs.
• Compare Daily/Hourly usage by model or project in one Usage & Allowance Breakdown: tokens, API-equivalent cost or estimated Standard credits, with account-wide captured weekly allowance or credit balance on a separate scale. Inspect previous dates through the global range filter and retain exact readings, reset boundaries and unknown values in folded details.
• Compare observed model output-phase tok/s in Model Details and Daily/Hourly trends, with median, middle 50% range, sample counts and seven-day hourly windows.
• Run Capture Usage when you want current totals immediately.
• Set CODEX_HOME, scheduled capture or Manual only, and migrate compatible legacy usage caches entirely inside VS Code.
• Filter Usage by preset or inclusive custom local-calendar range and project, switch theme, review verified project transitions, keep the Agent Activity Daily Summary visible, and export complete CSV rows through the VS Code save dialog.
• Review global, model, and expandable project Image Generation activity without mixing it into language token or cost totals; incomplete history reports complete, pending, unavailable, and artifact counts.
• Inspect current Task Storage and explicitly analyze one selected task tree.
• See last capture, pending work, stale-source warnings, and ledger revision in the status bar.

Quick Start

1. Install the platform-specific Companion VSIX.
2. Run Codex Usage: Set Up Collector and choose a valid CODEX_HOME.
3. Choose a capture interval, or Manual only if you prefer explicit refreshes.
4. Run Codex Usage: Open Dashboard from the Command Palette.
5. Use Codex Usage: Capture Usage before manually deleting a task or whenever the scheduled interval is not fresh enough.

The Companion's collector is parent-bound: automatic capture stops when VS Code closes. It continues while VS Code is open, even if the dashboard panel is closed. Quota snapshots missed while VS Code is closed cannot always be reconstructed later. The Plan Allowance meter marks each reading current, partially refreshed, or last known and shows its local observation time. The default interval is 15 minutes.

Plan Allowance compares Recent, Daily and Cycle average forecasts with the captured reset. Each row shows its actual observed span, a local run-out date and approximate days/hours before reset, or the percentage that would remain. Full dates and timezone offsets are available on hover. These are conditional projections, not guarantees; their calculations and freshness limits are unchanged.

Dedicated codex-auto-review approval checks are free for ChatGPT subscription use after the October 6 announcement. Their tokens stay visible, but estimated Standard credits are zero and they do not add uncertainty to allowance valuation. They remain API-excluded because OpenAI has not published a USD API rate for this model. Earlier unknown prices and ordinary model-based code reviews are unchanged.

Commands

Usage And Capture

Both collectors bundle official SQLite 3.54.1. Idle WAL maintenance preserves source history and defers physical reclamation while readers or writers are busy. There is no 512 MiB derived-data cap or automatic sidecar sweep; the existing report path remains in use.

Usage reports, Agent Activity, and its CSV export come entirely from CODEX_HOME/.codex-usage/usage-ledger.sqlite3. Changing range, project filter, theme, Agent Activity, or export does not reopen Codex task files. Custom ranges require inclusive YYYY-MM-DD start and end dates in the collector's configured timezone; malformed, reversed, and future dates are rejected. Agent Activity shows daily totals immediately and at most 50 agents in a collapsed disclosure, while CSV retains every selected agent-day row. Project Breakdown separates root tasks and structured subagents, then stacks each role by model. Side-chat usage remains under the parent root task where Codex does not store a durable role discriminator.

Each role cell shows both tokens and API-equivalent dollars. Use the shared Compare by control to change both Project Breakdown and Model Mix between Tokens and API cost without regenerating the report. Models are shown by generation and product tier with stable, distinct colors; the bounded visual set still prioritizes the models responsible for the most tokens.

Project Economics adds a weighted all-project benchmark and expandable project and model turn metrics from the same selected ledger rows. Distinct non-empty project/task/turn identities define turns; blank turn IDs remain in totals and coverage, while unpriced turns are excluded only from cost denominators. Detailed Token Accounting is collapsed by default, and Cache Write (reported) is copied from the ledger rather than inferred or reconstructed.

Image Generation reporting uses only durable image-event metadata. It keeps operations, outputs, model evidence, exact values, and unpriced coverage separate from language accounting; prompts, paths, bytes, and image contents are not retained. Unknown or conflicting model evidence is shown as unpriced rather than estimated.

Historical image and speed recovery participate in startup, scheduled, and manual captures, sharing no more than four 16 MiB rollout slices (64 MiB total). Recent sources are prioritized while older sources and image owners make fair progress. Missing or unmeasurable timing is explicit; captured language and image evidence remain unchanged. Deleted or untimed logs cannot supply missing timing evidence.

Pricing is bundled and effective-dated. Exact GPT-6.1 Terra usage is recognized from October 26, 2026, alongside GPT-6.1 Sol, GPT-6 Astra, Sol and Luna. Terra's Standard API input/cached/output estimates are $1/$0.05/$5 per million tokens, with $1.25 for 30-minute cache writes and the full-request long-context adjustment above 272K input tokens. Standard input/cached/output credit estimates are 25/1.25/125 per million tokens, with no separate cache-write surcharge. Earlier activity remains visibly unpriced. See the Terra model page, API pricing table and Codex credit rates. Other credit estimates use published standard token rates and intentionally omit plan-specific or Fast-mode multipliers because task records do not identify them reliably.

The collector normally checks every configured interval. Unchanged cycles may inspect filesystem metadata but open zero JSONLs; ordinary growth reads only guard windows and the new tail. Capture Usage coalesces with existing capture work and resets the next interval after success. Usage refreshes automatically and has no separate reload icon. Task Storage retains its reload icon, and Reload Current View remains available in the Command Palette without capture.

Deleted source tasks remain in historical totals only after their latest usage was captured. Run Capture Usage before deleting. Codex Usage cannot restore a deleted task.

Observed Output Speed

Model Details summarizes the complete selected range and project filter. Daily trends use local calendar days; Hourly uses navigable seven-local-day windows without changing the global filters or summary. Repeated DST hours keep their distinct offsets. Capture refresh preserves granularity and window. All Projects includes future projects; all checked current projects remain an explicit fixed subset.

Eligible responses contain at least 500 output tokens, counting reasoning once. Points require five responses; five through nineteen are marked small sample. Detail exposes the median, middle 50% range and task/source counts. Gaps are missing or insufficient evidence, not zero speed. Recovery and exclusions are available in folded diagnostics.

This is client-observed output-phase speed, not pure server decode speed, first-token latency or end-to-end task throughput. Ambiguous, conflicting and tool-overlapping evidence is excluded. Workload mix, routing, client timing and missing logs limit comparisons; trends do not establish a rollout's causal or universal gain. Timing storage retains no prompts, answers or reasoning text.

Task Storage

Task Storage reports current active and archived JSONL bytes by user-visible root task tree and separates root files from structured descendants. It does not follow the Usage date range. It shares the selected project filter and explicit Auto, Day, or Night theme with Usage.

Choose Analyze on a tree to scan only that tree for repeated compacted history, inline-media evidence, descendant concentration, and active-root risk. The operation is cancellable and does not invoke a model. History amplification is labeled only after a complete analysis finds at least 1 GiB of compacted rows representing at least 50% of logical tree bytes; otherwise the result remains Not analyzed, incomplete, or below threshold.

• Use Fork in Codex for conversational continuity; it is not a backup or a disk-reduction guarantee.
• Use a fresh task with a concise handoff when reducing inherited context is the priority.
• Verify the replacement before manually archiving or deleting the original.

Codex Usage does not create, fork, archive, restore, or delete tasks.

Task Transfer

Task Transfer was retired in 2.13.0. Import, Export, Review Status and the transfer CLI are no longer supported.

Existing chats, transfer folders, exported files and paired-transfer state remain untouched. The saved transfer-folder path is preserved as inert legacy settings data and is not accessed. There is no automatic migration, reimport or cleanup.

Use Codex native host handoff for ongoing work. It requires connected hosts and matching saved Git projects, transfers the chat and Git state, and can interrupt active work. It is not an offline-recovery or non-Git migration tool, and it is not a backup. Old exports remain user-owned; older companion versions are not guaranteed compatible with future Codex releases.

Settings

• codexUsage.range: dashboard range; default 30d.
• codexUsage.theme: auto, day, or night.

Project selections are Companion UI state. Use Set Up Collector for CODEX_HOME, capture interval, Manual only, and legacy-cache migration. A previously registered native background service can be retired through the explicit Command Palette handoff. Keep the shared .codex-usage directory when uninstalling the old app; Reset Local Data is not a handoff step.

Privacy

The companion connects only to the authenticated collector on 127.0.0.1. Its webview never receives the bearer token. It has no telemetry and does not upload task content. See the full privacy policy.

For support, open a GitHub issue and include the extension version, operating system, collector status, and redacted Codex Usage output. Never attach raw task JSONLs publicly.

Plan Allowance

Three compact conditional pace rows beneath each active meter show Recent (up to 60 minutes), Daily (up to 24 hours, with six-hour recency decay), and Cycle (the entire observed coherent window, including idle time). Each shows its actual observed span; Cycle does not assume the reset instant was captured or invent a zero-percent starting point. All compare signed movement with the captured reset in your configured timezone; they may disagree. They describe what would happen if the measured pace continued, without promising future usage. Sparse or conflicting evidence stays unmeasurable. Failed, stale or expired predictions await fresh capture; opening a view does not restart them. Method and evidence diagnostics stay in the existing allowance disclosure.

The account-wide Plan Allowance section shows active quota buckets and reset metadata, plus the Observed API-equivalent value of full allowance when a window has a valid priced fit. Fits need at least 10 percentage points; stronger confidence also requires completed windows and the documented coverage and sensitivity gates. If the newest window is not yet priceable, the headline can show a dated Previous window estimate from the same limit, plan, and duration series. It never borrows across series. Collapsed diagnostics list recent valid priced windows, including current and provisional fits. Project and date filters do not change this account-wide section.

The heading also shows the latest observed account-wide credit balance when available, with exact precision on hover and older balances marked last known. Folded capture details show adjacent balance changes, not authenticated bills. These balances are separate from estimated token credits and banked resets; history starts prospectively with live captures. Allowance fits stop before the first reported-full quota reading, preserving raw evidence and ordinary costs without attributing later usage to a payment source.

Captures use official Codex App Server metadata reads without a model turn. Unavailable probes do not fail ordinary capture. Historical recovery checks registered sources newest-first with bounded endpoint reads, up to 8 MiB per capture, and resumes automatically. Recovery is partial, with provenance and coverage disclosed. Upgrades back up and preserve existing usage and checkpoints. Report navigation reads only the ledger. No account identity, authentication, prompts, or content is retained by allowance collection.

This is a local workload-specific API-equivalent estimate, not cash value or a contractual entitlement. Other-device usage, missing history, model mix, and pricing can affect it. Lifetime account tokens are coverage diagnostics only.