Skip to main content
plugin CX Codex

codex-usage-tracker — Claude Code plugin: install and use

codex-usage-tracker is a Claude Code plugin that reads local Codex session logs for token summaries, session details, CSV exports, and dashboards.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-usage-tracker@awesome-codex-plugins
Open on GitHub

What codex-usage-tracker does

codex-usage-tracker turns local Codex session metadata into MCP results for aggregate usage summaries, session-level inspection, CSV export, and dashboard generation. It works with evidence from local logs rather than a hosted usage feed.

The runtime needs the Python package codex-usage-tracking==0.28.0 installed through pipx. Add the plugin from the Claude Code marketplace, then start a fresh task so the new MCP tool catalog is discovered. Its supported runtime uses SQLite; the replacement runtime does not open or migrate the old database.

What it helps with

  • summarize token use across local Codex sessions
  • inspect one session and its tool calls
  • export Codex usage records as CSV
  • generate a dashboard from session logs

Example prompts for the agent

  • Summarize Codex token usage across my recent local sessions.
  • Show the details and tool calls for this Codex session.
  • Export the Codex usage data to CSV and generate a dashboard.

How to install codex-usage-tracker

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install codex-usage-tracker@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about codex-usage-tracker

How do I install codex-usage-tracker in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install codex-usage-tracker@awesome-codex-plugins. Start a fresh Claude Code task after installation.

What does codex-usage-tracker do?

It reads local Codex session metadata through MCP tools and produces aggregate summaries, session details, CSV exports, and dashboards.

What does codex-usage-tracker need to run?

It needs the Python package codex-usage-tracking==0.28.0 installed with pipx, plus local Codex session logs. A fresh task is required after installation so Claude Code discovers the plugin tool catalog.

Source text

codex-usage-tracker · MIT
# Codex Usage Tracker

[![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking)](https://pypi.org/project/codex-usage-tracking/)
[![Python](https://img.shields.io/pypi/pyversions/codex-usage-tracking)](https://pypi.org/project/codex-usage-tracking/)
[![CI](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml/badge.svg)](https://github.com/douglasmonsky/codex-usage-tracker/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/douglasmonsky/codex-usage-tracker)](LICENSE)

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](docs/INDEX.md), read the
[product direction](docs/decisions/PRODUCT_DIRECTION.md), or follow the
[clean-cutover roadmap](docs/roadmap/AGENT_FIRST_CLEAN_CUTOVER.md). Progress is
tracked in the [checkbox ledger](docs/roadmap/TASK_PACKETS.md), with one
complete contract per file under [`docs/roadmap/tasks/`](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:

```bash
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

```bash
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.

© Douglas Monsky · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
contam-tools The contam-tools plugin connects an agent to a local CONTAM MCP server to inspect project files, run simulations, and review outputs. It fits workflows built around .prj models and ContamW. CX Codex ★ 1,596repo stars computer-usage-summary-skill computer-usage-summary-skill turns local ActivityWatch data into a daily report of app time, AFK, a timeline and foreground browser pages. Nothing leaves the machine. CX Codex ★ 1,596repo stars cometchat-skills Adds CometChat text chat, voice, and video calling skills to React, Angular, React Native, iOS, Android, and Flutter projects using the live Docs MCP. CX Codex ★ 1,596repo stars cohesivity Connect a coding agent to Cohesivity services for hosting, Postgres, email, and more through MCP or an API. CX Codex ★ 1,596repo stars codex-tools-bridge codex-tools-bridge configures an experimental MCP bridge connecting ChatGPT Web to local Codex tools. It helps run local shell commands and edits directly from the web chat without a second model loop. CX Codex ★ 1,596repo stars codex-seo The codex-seo plugin for Claude Code and Codex runs site-wide or focused SEO checks on pages, technical issues, content, and backlinks. CX Codex ★ 1,596repo stars codex-reset codex-reset is a Claude Code plugin that connects read-only MCP tools for Codex limits. It reports a 24- or 48-hour reset forecast, verified reset records, and service status. CX Codex ★ 1,596repo stars codex-obsidian codex-obsidian connects your agent to local Obsidian vaults via the official desktop CLI. Runs note queries, task rollups, and workspace controls. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open