Codex Usage Tracker plugin
A plugin and MCP tools show where Codex tokens, time, credits and money go, based on local session metadata.
- 196 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The plugin reads local Codex session metadata and keeps a database on disk.
Install
- Works in
Manual install
pipx install "codex-usage-tracking==0.28.0"The first README step: the Python part in an isolated environment.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The plugin reads local Codex session metadata and keeps a database on disk.
This is third-party code. Review the repository files before installing.
What it does
Codex Usage Tracker turns local Codex session metadata into exact, checkable facts about how work consumes tokens, time, tools, allowance, credits and cost. The agent asks questions over MCP and gets compact selections with stable evidence links, then builds the explanation itself. The current 0.28.0 release keeps six MCP tools, an Evidence Console and a SQLite kernel. The Python part installs through pipx, and the plugin is added from the repository as a Codex marketplace and launches the `codex-usage-tracker` executable. All data stays on your machine.
Who it is for. Codex users working out why a session burned through its limit or credits who want numbers, not a guess.
Good fit when
- The allowance ran out early and the heaviest sessions must be found.
- Task cost is compared with and without caching.
- An agent explains from metadata which tools took the most time.
- Credit use is analysed by day and by session with links to concrete records.
Not a fit when
- You need cost tracking for other agents such as Claude Code.
- You want a polished general dashboard rather than facts for an agent.
- You need a cloud dashboard for a team.
Example request
Find the three Codex sessions that used the most credits this week and explain which tools and calls drove the spend.Limitations
Works only with Codex and reads its local logs. Version 0.28.0 is a frozen oracle during a rewrite: the author is preparing a clean agent-first kernel and the old code will be removed before the new release. The new version will not open or migrate the old database. After installing you need a fresh Codex task, or the plugin tool catalog is not picked up. Do not share real logs, prompts and responses in public repositories.
How to disable. Disable the plugin with the Codex plugin removal command and run `pipx uninstall codex-usage-tracking`. Delete the local database and cache by hand.
FAQ
How do I install the plugin?
Run `pipx install "codex-usage-tracking==0.28.0"`, then `codex plugin marketplace add douglasmonsky/codex-usage-tracker --ref v0.28.0` and `codex plugin add codex-usage-tracker@codex-usage-tracker`.
What exactly is measured?
Tokens, time, tool calls, resources, allowance, credits and cost across sessions, turns and calls.
Does data go to the cloud?
No, the project is local-first: data comes from your Codex session metadata on the machine.
What happens to the project next?
The author is rewriting it as a compact agent-first kernel with a fast setup over 24 hours or all time. Version 0.28.0 stays supported for now.
Why does the plugin need pipx?
The plugin launches the `codex-usage-tracker` executable from the pipx environment, so the Python part installs separately and in isolation.
Discussion
No questions or reviews yet.
Related
PluginsA CLI that shows Codex usage limits and the number of manual resets, and spends one reset after explicit confirmation.
A Codex skill for safe local-state maintenance: a report-only default, backup and archive instead of deletion, log and worktree cleanup
TokenTracker counts tokens and spend across Claude Code, Codex, Cursor, Gemini CLI and other agents from local logs and shows them on a local dashboard
A CLI and MCP server that tally token spend across 41 tools and agents, break it down by project and model, and help cut wasted tokens
Counts token use and cost of Claude Code and Codex sessions from local logs and shows remaining limits in the status line
Splitrail tracks tokens and cost for Claude Code, Codex, Cline, OpenCode and more agents from local logs and serves them over MCP
README in short
The project calls itself a local data product for questions about Codex consumption. Further work is described in the PRODUCT_DIRECTION document and a task list with a contract for each item.