See where your OpenAI Codex tokens go. One command.

codex-spend is a local dashboard for analyzing OpenAI Codex CLI usage. It parses your local Codex session/state data and visualizes token usage, estimated cost, and actionable patterns to help reduce spend.

• ⚡️ Instant Terminal Summary: High-level breakdown of your recent sessions directly in your terminal on startup.
• 🛡️ Local & Private: Your Codex usage data is read locally; the dashboard runs on 127.0.0.1 and nothing is uploaded.
• 📈 Usage Analytics: Daily token usage charts, model breakdowns, cache hit rates, and token category splits.
• 💡 Actionable Insights: Detects "One-Word Reply" traps, "Tab Hoarder" habits, context window overflows, reasoning ROI, and more.
• 📂 Project Breakdown: See exactly which repositories or directories consume the most tokens.
• 💰 Accurate Cost Estimates: Includes prompt caching discounts and reasoning tokens. Covers all current Codex models.
• 📋 Subscription Plan Mode: If you pay a flat monthly fee instead of per-token, run with --plan to reframe costs as API Equivalent Value and see a rolling 5-hour and 7-day usage estimate.

Run it instantly without installation using npx:

npx codex-spend

If you use Codex via a ChatGPT Plus ($20/mo) or Pro ($200/mo) subscription instead of paying per token, add --plan:

npx codex-spend --plan

This will:

• Relabel "Est. Cost" → "API Equivalent Value" so you see the value you extracted, not a scary cost number
• Show your estimated token usage in the last 5 hours and last 7 days vs. your plan limits (160 msgs / 5hrs, 3,000 thinking msgs / week on Plus)
• Link directly to your official OpenAI usage analytics page

When you run codex-spend, the tool:

1. Locates your Codex CLI state (usually ~/.codex).
2. Parses your state_n.sqlite database and sessions/ transaction logs.
3. Automatically opens a local dashboard at http://localhost:4321.

• Node.js >=18

• sqlite3 CLI installed on your system

  # macOS
  brew install sqlite
  
  # Ubuntu/Debian
  sudo apt-get install sqlite3

The dashboard uses official OpenAI API per-token pricing (verified July 2026):

If a model is unknown, the dashboard warns that total cost may be underestimated.

codex-spend is strictly a local analyzer.

• It never reads your API keys.
• It does not upload your Codex usage data anywhere.
• The source code is fully open for audit.

Distributed under the MIT License. See LICENSE for more information.

Rishet Mehra

• GitHub: @Rishet11
• LinkedIn: Rishet Mehra
• Email: [email protected]