Server · #244 trending MCP repo
Codex Usage Tracker
douglasmonsky/codex-usage-tracker
Local-first MCP tools and dashboard for investigating Codex token usage, credits, costs, caching, and thread patterns.
- Stars
- 197
- This week
- —
- Forks
- 18
- Open issues
- 13
- Skills inside
- 7
Inside this repo
7 skills
.claude/skills/gitnexus/gitnexus-cligitnexus-debuggingUse when the user is debugging a bug, tracing an error, or asking why something fails. Examples: "Why is X failing?", "Where does this error come from?", "Trace this bug".claude/skills/gitnexus/gitnexus-debugginggitnexus-exploringUse when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: "How does X work?", "What calls this function?", "Show me the auth flow".claude/skills/gitnexus/gitnexus-exploringgitnexus-guideUse when the user asks about GitNexus itself — available tools, how to query the knowledge graph, MCP resources, graph schema, or workflow reference. Examples: "What GitNexus tools are available?", "How do I use GitNexus?".claude/skills/gitnexus/gitnexus-guidegitnexus-impact-analysisUse when the user wants to know what will break if they change something, or needs safety analysis before editing code. Examples: "Is it safe to change X?", "What depends on this?", "What will break?".claude/skills/gitnexus/gitnexus-impact-analysisgitnexus-refactoringUse when the user wants to rename, extract, split, move, or restructure code safely. Examples: "Rename this function", "Extract this into a module", "Refactor this class", "Move this to a separate file".claude/skills/gitnexus/gitnexus-refactoringusage-kernelUse the six Codex Usage Tracker tools for exact local usage facts, bounded exploration, allowance observations, and evidence timelines.skills/usage-kernelDocumentation
README
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.
Releases