Codex Usage Tracker

Local-first dashboard, Codex plugin, and companion skill for understanding where your Codex tokens and usage credits are going.

Unofficial project: Codex Usage Tracker is an independent open-source project. It is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI; this project only reads local log files from your machine.

Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.

Built for developers using Codex locally who want to know which threads, models, projects, subagents, and long chats are driving usage without uploading logs anywhere. After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"

Highlights

The dashboard is organized into six views that take you from a one-glance health read down to a single call:

• Overview — an AI Usage Health score (cache reuse, context discipline, reasoning balance, clean calls), KPI cards with plain-language tooltips, charts for credits over time / token mix / credits by model, and a ranked "top sessions to review" list.
• Insights — Needs Attention cards, one-click investigation presets, a "what you are doing well" habit scorecard, and an efficient-use playbook.
• Calls — the main investigation table: filter, sort, inspect, and export the exact aggregate rows you are looking at.
• Threads — related calls grouped into work sessions so long chats, subagents, and auto-review passes read as one story.
• Learn — plain-language definitions of tokens, credits, caching, context windows, and reasoning effort, plus a copy-paste prompt template.
• Search & Chat — a local, rules-based assistant that answers questions about your filtered usage from aggregate data only.

Shared filters across Model, Project, Reasoning, Confidence, Time range, and free-text search apply to every data view, and a slide-in details drawer shows aggregate cost, cache, context, allowance, and pricing signals for any row.

Quick Install

Install this fork directly from GitHub with pipx:

python -m pip install --user pipx
python -m pipx ensurepath
pipx install "git+https://github.com/sisodiabhumca/Codex-Usage-Tracker.git"
codex-usage-tracker setup
codex-usage-tracker serve-dashboard --open

Use your normal Python launcher for your platform: python3 is common on macOS/Linux, and py may be preferable on Windows. On macOS with Homebrew, brew install pipx is also fine. If codex-usage-tracker is not found after installing with pipx, open a new terminal or add the binary directory printed by pipx ensurepath to your PATH.

The installed command is codex-usage-tracker. serve-dashboard refreshes active-session usage before opening by default. Use --no-refresh only when you intentionally want to inspect the cached local index.

setup installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs codex-usage-tracker doctor, and tells you whether Codex needs a restart for plugin discovery.

If you only want plugin registration after installing the package:

codex-usage-tracker install-plugin

More install paths: Install Guide.

Packaging note: the distribution and installed command are both named codex-usage-tracker, and the import package is codex_usage_tracker. Install this project from its repository at sisodiabhumca/Codex-Usage-Tracker.

After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: MCP And Codex Skills.

Platform Support

The core app is not macOS-only. The CLI, SQLite index, dashboard generator, and localhost server are Python-based and CI-tested on Ubuntu for Python 3.10-3.14. It defaults to ~/.codex for local Codex logs and ~/.codex-usage-tracker for tracker data; pass --codex-home or --db when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run codex-usage-tracker doctor after setup if plugin registration does not appear in Codex.

Dashboard Tour

Start on Overview for a single health read on how you are using Codex and where the credits go.

Insights ranks what needs attention, surfaces the habits you are already doing well, and includes a credit-saving playbook.

The Calls table is the main investigation surface: filter by model, project, reasoning, confidence, and time, then sort, inspect, and export exactly what you see.

Threads groups related calls so long chats, subagents, and auto-review passes are easier to reason about as one work session.

The slide-in details drawer keeps primary cost, cache, context, allowance, and pricing signals visible before raw identifiers, with recommendations for flagged calls.

Learn explains every term in plain language so anyone on the team can read the dashboard.

Search & Chat answers questions about your filtered usage locally, from aggregate data only.

All dashboard screenshots use synthetic aggregate fixture data. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the Dashboard Guide for the full walkthrough.

If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.

Why This Exists

Codex can quietly burn usage through long-running chats, low cache reuse, reasoning spikes, spawned subagents, and auto-review passes. This tool turns the aggregate counters already on your machine into an insight-first dashboard and scriptable local APIs.

Use it to answer:

• Which threads used the most tokens, estimated cost, or Codex credits?
• Are long chats bloating because of accumulated context?
• Which model or reasoning effort is driving usage?
• Are subagents or auto-review passes adding unexpected cost?
• Which calls have low cache reuse, high context pressure, reasoning spikes, or pricing gaps?
• Which projects, project tags, or active directories are consuming the most usage?
• What should Codex inspect next using the companion usage skill?

Long Chats Can Bloat Fast

Prompt caching helps, but cached input is not the same as no input. Long threads can accumulate a large cached context, and each new turn may still include cached input plus fresh uncached input, output tokens, reasoning output, and tool-related context.

The dashboard makes that pattern visible with Cached input, Uncached input, Session cumulative, Context use, and Cache ratio.

Practical takeaway: when old context is no longer useful, starting a fresh thread can be more efficient than dragging a large cached history forward. That is not a rule for every task, but it is one of the clearest usage patterns the tracker is designed to reveal.

First Useful Workflow

codex-usage-tracker update-pricing
codex-usage-tracker update-rate-card
codex-usage-tracker setup
codex-usage-tracker serve-dashboard --open

Then:

1. Leave Live enabled while working, or click Refresh after a Codex run finishes.
2. Start on Overview to read the health score and where credits are going.
3. Move to Insights and scan the Needs Attention cards and presets.
4. Use the Project, Model, and Time filters (presets or calendar fields) to focus the whole dashboard.
5. Open Threads to see how a conversation grew and whether subagent or auto-review work attached to it.
6. Click any row to inspect aggregate fields in the details drawer.
7. Use Load context only when aggregate fields are not enough; context is fetched on demand from the local source JSONL and is not saved into SQLite or the dashboard.
8. Visit Learn or Search & Chat when you want definitions or a quick answer about your own numbers.

Optional allowance context:

codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"

The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. Allowance values are only as accurate as the values you manually copy from Codex Settings, /status, or another trusted usage display. Details: Pricing, Credits, And Allowance.

What It Includes

• Local SQLite index at ~/.codex-usage-tracker/usage.sqlite3.
• Static dashboard generation plus localhost live refresh.
• Six dashboard views: Overview, Insights, Calls, Threads, Learn, and Search & Chat.
• Shared Model, Project, Reasoning, Confidence, Time, and search filters with a slide-in details drawer.
• Active-only dashboards by default, with an explicit All history toggle for archived sessions.
• CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
• MCP tools for Codex sessions that want to query local usage data.
• Companion Codex skills for operational setup and conversational usage analysis.
• Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.

Common Commands

codex-usage-tracker summary --preset last-7-days
codex-usage-tracker query --since 2026-06-01 --min-credits 1
codex-usage-tracker session <session-id>
codex-usage-tracker export --output usage.csv
codex-usage-tracker open-dashboard
codex-usage-tracker support-bundle --output ~/.codex-usage-tracker/support-bundle.json

Full command reference: CLI Reference.

Data Privacy

The tracker stores aggregate metrics only: session ids, timestamps, local source paths, thread labels, cwd/project metadata, model labels, reasoning effort, token counters, pricing/credit annotations, and derived ratios.

It does not store prompts, assistant messages, tool output, pasted secrets, raw transcript snippets, or raw context in SQLite, CSV exports, generated dashboard HTML, or synthetic screenshots.

On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can start off until you enable it from the details panel:

codex-usage-tracker serve-dashboard --no-context-api --open

For shared artifacts, use:

codex-usage-tracker --privacy-mode redacted dashboard --open
codex-usage-tracker --privacy-mode strict export --output usage-redacted.csv

Full model: Privacy Guide.

Documentation

• Install Guide
• Dashboard Guide
• CLI Reference
• Pricing, Credits, And Allowance
• MCP And Codex Skills
• Privacy Guide
• Architecture
• CLI And MCP JSON Schemas
• Development And Release

Current Limitations

• This is a sidecar dashboard and plugin, not a native Codex chat overlay.
• Codex upstream log formats can change, and parser compatibility may require tracker updates.
• Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
• Pricing and rate-card sources can change outside this project.
• Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
• Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
• Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
• The Search & Chat assistant is a local, rules-based helper over your aggregate data; it does not call any external model.

Development

git clone https://github.com/sisodiabhumca/Codex-Usage-Tracker.git
cd Codex-Usage-Tracker
python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install ".[dev]"
python -m pytest

Run the full local CI gate before pushing to main. See Development And Release.