Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.claude/skills/gitnexus		.claude/skills/gitnexus
.codex-plugin		.codex-plugin
.codex		.codex
.github		.github
.serena		.serena
assets		assets
config		config
docs		docs
experiments/physical-architecture		experiments/physical-architecture
frontend/kernel-console		frontend/kernel-console
requirements		requirements
scripts		scripts
skills/usage-kernel		skills/usage-kernel
src/codex_usage_tracker		src/codex_usage_tracker
tests		tests
tools/gitnexus		tools/gitnexus
.bandit		.bandit
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.markdownlint-cli2.yaml		.markdownlint-cli2.yaml
.mcp.json		.mcp.json
.yamllint		.yamllint
AGENTS.agent-maintainer.md		AGENTS.agent-maintainer.md
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
SECURITY.md		SECURITY.md
dependency-cruiser.config.cjs		dependency-cruiser.config.cjs
justfile		justfile
knip.json		knip.json
package-lock.json		package-lock.json
package.json		package.json
playwright.config.mjs		playwright.config.mjs
pyproject.toml		pyproject.toml
stylelint.config.mjs		stylelint.config.mjs
tach.toml		tach.toml
zizmor.yml		zizmor.yml

Repository files navigation

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.