Cost Tracking & Usage Analytics

What feature would you like to see?

Status: RFC (Request for Comments)
Proposer: @Aki-07
Target: Codex CLI v0.3.0+

Problem Statement

Current State:
Codex CLI users currently have no visibility into how much their sessions cost or how tokens are consumed. This lack of transparency causes:

• Unpredictable bills: Users run --full-auto or long sessions without knowing the cost.
• No budget control: There’s no way to set usage limits.
• Inefficient model choices: Developers can’t compare the cost efficiency of models.
• No team accountability: Organizations can’t track usage per project or member.
• Hidden expenses: Large-model sessions (e.g., o3 vs o4-mini) differ drastically in cost, but users can’t see that in real time.

Proposed Solution

Add a built-in cost and usage analytics module to the Codex CLI.
This system would track, summarize, and visualize API usage in real time and historically.

Core Capabilities

• Real-time Cost Visibility: Show approximate running cost and token count during each session.
• Historical Usage Summaries: View daily, weekly, and monthly cost reports.
• Budget Controls: Set soft or hard limits (warn or block once exceeded).
• Per-Project Tracking: Attribute usage to the current working directory or Git project.
• Export & Integration: Allow exporting cost data to JSON/CSV for analysis.

High-Level Architecture

Components:

• Cost Tracker: Intercepts API responses to record token counts and models used.
• Calculator: Uses public model pricing to estimate per-session costs.
• Storage: Saves records locally (e.g., ~/.codex/usage/).
• Aggregator: Provides summaries by time period, model, or project.
• Budget Manager: Reads user-configured limits and enforces warnings or soft blocks.
• Display Layer: Pretty terminal summaries and optional real-time TUI widgets.

Impact Metrics

User-Facing Improvements

• ~50% faster optimization of workflows through cost visibility.
• ~3× increase in efficient model selection.
• Predictable spending and better budgeting for individuals and teams.

Technical Goals

• 90% accuracy between estimated and actual billed usage.
• Real-time display overhead <10% of normal CLI performance.

Duplicate Check & Relationship to Existing Issues

The following related issues were flagged automatically:

| Related Issue | Summary | Relationship to This Proposal |
|----------------|----------|--------------------------------|
| #3201: Add token usage or cost information to the rollout files | Requests showing token usage or session cost data (per session or rollout). | Partially related: my proposal builds on this by introducing a comprehensive cost tracking and analytics system, including real-time cost display, historical summaries, budgets, and project-level aggregation. |
| Other token usage or /status issues | Focus on showing cache tokens, model breakdowns, or per-request stats. | Complementary: these are about display fidelity per run, whereas this RFC is about persistent usage analytics and budget control across all sessions. |

Summary:
While #3201 correctly identifies the need for transparency around cost and token usage, this RFC proposes a system-wide solution covering real-time feedback, daily/weekly/monthly summaries, project-level insights, and budget limits.
It goes beyond per-session reporting to make Codex cost-aware, auditable, and predictable for individuals and teams.
Therefore, this is not a duplicate, but a natural evolution and extension of that earlier idea.