codex-usage-tracker

Name: codex-usage-tracker
Author: douglasmonsky

Verified

Local-first MCP tools and dashboard for investigating Codex token usage, credits, costs, caching, and thread patterns.

160stars

12forks

Python

Installation

# Add to your Claude Code skills
git clone https://github.com/douglasmonsky/codex-usage-tracker

Getting Started

Guides for using mcp servers skills like codex-usage-tracker.

Best MCP Servers in 2026
Category-by-category picks: databases, dev tools, productivity, browser automation.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills
First-time install walkthrough for Claude Code, Codex CLI, and ChatGPT.

Security ReportVerified

Last scanned: 7/15/2026

{
  "issues": [],
  "status": "PASSED",
  "scannedAt": "2026-07-15T06:13:16.916Z",
  "npmAuditRan": true,
  "pipAuditRan": true,
  "promptInjectionRan": true
}

README.md

Frequently Asked Questions

What is codex-usage-tracker?

codex-usage-tracker is an open-source mcp servers skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by douglasmonsky. Local-first MCP tools and dashboard for investigating Codex token usage, credits, costs, caching, and thread patterns. It has 160 GitHub stars.

Is codex-usage-tracker safe to use?

Yes. codex-usage-tracker passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.

How do I install codex-usage-tracker?

Clone the repository with "git clone https://github.com/douglasmonsky/codex-usage-tracker" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is codex-usage-tracker written in?

codex-usage-tracker is primarily written in Python. It is open-source under douglasmonsky on GitHub, so you can review or fork the full source.

Are there alternatives to codex-usage-tracker?

Yes. SkillsLLM lists many other MCP Servers skills you can browse and compare side by side. Open the MCP Servers category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh codex-usage-tracker against similar tools.

MCP for Beginners

Build MCP servers that give AI assistants real capabilities

36 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

ECC

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

229,808

Popular in MCP Servers

Top skills in this category by stars

Scrapling

by D4Vinci

🕷️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!

69,577

web3-research-mcp zettelkasten-mcp

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 plus local content/tool/command/file-event evidence into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. The content index stays on your machine; CSV exports, generated dashboard HTML, support bundles, and shareable reports omit indexed content by default. Use refresh --aggregate-only or rebuild-index --aggregate-only when you want the older aggregate-only SQLite posture.

Cloned Codex tasks can copy historical usage rows into a new local log. The tracker preserves those physical rows for provenance but excludes only strict, high-confidence fingerprint matches from default dashboard, API, MCP, summary, recommendation, allowance, and export totals. New calls made inside the clone remain billable. Inspect the exclusion count with codex-usage-tracker dedupe-diagnostics --json, MCP usage_dedupe_diagnostics(), or /api/diagnostics/dedupe.

Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is codex-usage-tracking, and it installs the codex-usage-tracker command.

After install, you get a localhost dashboard, a local SQLite usage index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"

Quick Install

python -m pip install --user pipx
python -m pipx ensurepath
pipx install codex-usage-tracking
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.

First install? Start with the First Five Minutes guide for setup, verification, empty-dashboard checks, and safe issue diagnostics.

serve-dashboard refreshes active-session usage before opening the React dashboard by default. The legacy dashboard remains available at /dashboard.html on the same localhost server. Use --no-refresh only when you intentionally want to inspect the cached local index.

Package naming: the PyPI distribution is codex-usage-tracking; the installed command is codex-usage-tracker; the GitHub repository remains douglasmonsky/codex-usage-tracker. The codex-usage-tracker PyPI name is not this project, so avoid similarly named packages when following these docs.

Source install for development or branch testing:

pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"

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

Want Codex to do it for you? Paste: Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard.

Talk To Your Usage Data

The dashboard shows the evidence; the companion plugin and skills make it conversational. After setup and a Codex restart, ask Codex to refresh the local usage index, call MCP tools, and explain what is driving usage. Shareable reports stay aggregate-first and omit indexed content unless an explicit local content tool/export is added for that purpose.

Good starter prompts:

Look through my usage for token waste and recommend what I should change.
Find high-context, low-cache calls worth opening in the investigator.
Which threads are draining the most, and what would reduce that next time?
Compare model and effort usage, then suggest safer defaults.
Open the dashboard and filter Calls to the rows behind your recommendation.

The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Allowance Intelligence, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.

Example conversation docs:

Dashboard Preview

Overview is the dashboard landing workspace: it shows recent aggregate usage, weekly remaining usage context, row loading controls, and charts that open on recent dates.

Overview view showing high-level metrics, row loading controls, time-series charts, and recent aggregate calls.

Calls is the high-density investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.

Calls view showing the expanded model-call table with sticky thread rows and detail controls.

The details rail stays beside the model-call table, so you can inspect aggregate call accounting before opening a full investigator route.

Calls view showing the expanded model-call table beside the Call Drill-Down detail rail.

Click a call row to open the dedicated investigator for exact token accounting, cache/accounting deltas, local serialized evidence buckets, and runtime-only evidence controls.

Call investigator showing token accounting, cache diagnostics, serialized evidence groups, and evidence controls.

The lower investigator view keeps local JSONL context gated behind explicit localhost actions; raw context is not embedded in generated dashboard HTML.

Lower call investigator view showing context estimates and the explicit raw-context evidence gate.

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

Threads view with one expanded thread and its calls.

Diagnostics Notebook surfaces on-demand snapshot reports for usage drain, tool output, commands, Git interactions, file reads, file modifications, read productivity, and concentration without tying them to the normal live refresh loop.

Diagnostics Notebook view showing diagnostic snapshot modules and usage-drain reporting.

Dashboard screenshots use synthetic aggregate fixture data, and companion prompt/chat previews are synthetic. They do not contain prompts, local logs, assistant responses, real 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.

Companion Skill And Plugin

The dashboard is the core product surface. The Codex plugin and companion usage skills let Codex refresh local aggregates, call MCP tools, and explain usage patterns conversationally after plugin discovery. Setup and tool details: MCP And Codex Skills.

If you only want plugin registration after installing the package:

codex-usage-tracker install-plugin

More install paths: Install Guide.

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. The installed-package Docker smoke path uses python:3.14-slim by default so packaged resources and CLI entry points are exercised on the newest supported runtime. It defau