Codex Usage Tracker

Codex Usage Tracker is a local usage-data product for answering questions about how Codex work consumes tokens, time, tools, allowance, credits, and cost. It turns local session metadata into exact, bounded facts and stable evidence that an agent can explore and explain.

Current release and next direction

Version 0.28.0 is the current public release. Its six-tool MCP surface, Evidence Console, and SQLite kernel remain supported while the replacement is qualified.

The next product is a clean, agent-first kernel rather than a larger dashboard:

• fast recent-history setup with explicit 24-hour through all-time coverage;
• incremental reuse on every later invocation;
• exact session, turn, call, tool, resource, allowance, token, credit, and cost facts;
• compact named queries and stable evidence selectors;
• agent-owned interpretation instead of server-authored narrative findings;
• installed Codex qualification measured for latency, MCP calls, response bytes, model tokens, accuracy, and usefulness.

The 0.28 code remains a frozen oracle during the rewrite and is removed before the clean replacement release. The new runtime does not migrate or open its database.

Start with the documentation authority, read the product direction, or follow the clean-cutover roadmap. Progress is tracked in the checkbox ledger, with one complete contract per file under docs/roadmap/tasks/.

Install 0.28.0

Install the Python runtime into an isolated executable environment, then add the matching tagged repository as a Codex plugin marketplace:

pipx install "codex-usage-tracking==0.28.0"
codex plugin marketplace add douglasmonsky/codex-usage-tracker --ref v0.28.0
codex plugin add codex-usage-tracker@codex-usage-tracker

The plugin launches the codex-usage-tracker executable from the pipx environment. Start a fresh Codex task after installation so it discovers the new plugin tool catalog.

Develop

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
just v

Use synthetic fixtures only. Do not commit or share real Codex logs, prompts, responses, tool-output bodies, credentials, private paths, or local databases.