💸 Codex-Spend

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.

✨ Features

• ⚡️ 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.

🚀 Quick Start

Run it instantly without installation using npx:

npx codex-spend

CLI Options

| Flag | Description | Default | | :--- | :--- | :--- | | --port <number> | Change the local server port | 4321 | | --state-db <path> | Override Codex state DB path (advanced) | auto-detect latest | | --no-open | Skip automatic browser opening | | | --plan | Subscription plan mode (shows API Equivalent Value + usage estimate) | | | --help | Show usage instructions | |

Subscription Plan Mode

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

🛠️ How it Works

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.

Requirements

• Node.js >=18

• sqlite3 CLI installed on your system

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

💰 Model Pricing Coverage

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

| Model | Input / 1M | Cached Input / 1M | Output / 1M | | :--- | :--- | :--- | :--- | | gpt-5.5 | $5.00 | $0.50 | $30.00 | | gpt-5.4 | $2.50 | $0.25 | $15.00 | | gpt-5.3-codex | $1.75 | $0.175 | $14.00 | | gpt-5.2-codex | $1.75 | $0.175 | $14.00 | | gpt-5.1-codex-max | $1.25 | $0.125 | $10.00 | | gpt-5.2 | $1.75 | $0.175 | $14.00 | | gpt-5.4-mini | $0.75 | $0.075 | $4.50 | | gpt-5.1-codex-mini | $0.25 | $0.025 | $2.00 |

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

🔐 Privacy

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.

📝 License

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

👨‍💻 Author

Rishet Mehra

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