# Codex Usage Tracker

> Use when the user asks about Codex token usage, model/reasoning efficiency, usage dashboards, CSV exports, or per-session/per-turn Codex usage stats from local logs.

- Skill: `thedixitjain/codex-usage-tracker` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add thedixitjain/codex-usage-tracker`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thedixitjain/codex-usage-tracker/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: thedixitjain (https://skillmd.com/u/thedixitjain)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/thedixitjain/codex-usage-tracker

---



# Codex Usage Tracker

Unofficial project: Codex Usage Tracker is independent and is not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. OpenAI and Codex are trademarks of OpenAI.

Use this plugin to inspect aggregate token usage from local Codex session logs.

## Privacy Boundary

The index, dashboard payload, CSV export, and normal summaries are aggregate-only. They should never return prompts, assistant message text, tool outputs, pasted secrets, or raw transcript snippets.

The only exception is `usage_call_context`, which intentionally reads one selected record's source JSONL on demand. It requires `CODEX_USAGE_TRACKER_ALLOW_RAW_CONTEXT=1` in the MCP server environment. Use it only when the user explicitly asks to inspect actual context, and mention that returned text is local, redacted, size-limited, and not persisted by the tracker.

## Fast Paths

- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. On macOS, first run `codex-usage-tracker dashboard-service status`. If it is healthy, open or report its persisted localhost URL (default `http://127.0.0.1:47821`) without starting another server. If it is absent or unhealthy, start the live localhost dashboard with `codex-usage-tracker serve-dashboard --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Keep a foreground server running while the user is using it.
- For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Use the tracker API: refresh the aggregate index, then rank threads with `usage_summary(group_by="thread", limit=10, response_format="json")`.
- If MCP tools are unavailable for thread-ranking requests, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`. The summary is already ordered by `total_tokens` descending.
- Answer thread-ranking requests directly from the summary rows. For the heaviest-thread question, lead with the first row's thread and total tokens; for leaderboard requests, show a compact ranked list.
- If the CLI command is missing for dashboard-open requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli serve-dashboard --context-api explicit --open`.
- If the CLI command is missing for thread-ranking requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli refresh --json` and `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli summary --group-by thread --limit 10 --json`.
- If neither command is available, say briefly that the tracker CLI is not on `PATH` and ask the user to run `codex-usage-tracker setup` or reinstall with `pipx`.
- Keep dashboard-open narration minimal: one short progress note if needed, then the localhost URL. Do not narrate plugin discovery.

## Suggested Usage Questions

When the user wants ideas, suggest concrete aggregate investigations:

- Look through my usage for token waste.
- Find calls where context got bloated.
- Show me where caching failed.
- Which threads are draining the most?
- What changed recently?
- Check whether weekly allowance behavior changed.
- Explain why the 5-hour counter looks noisy.
- Build strict-privacy allowance evidence I can share.
- Find expensive calls worth opening in the investigator.
- Check whether model or effort choice is wasting tokens.
- Test my usage-waste hypotheses and say what was true, false, or inconclusive.
- Compare repeated file rediscovery, shell churn, and large low-output calls.
- Run Compression Lab to rank overlap-adjusted context and workflow waste candidates.
- Simulate which candidate fixes would save the most future context.
- Build a strict-privacy summary I can share.

Route broad waste and context-compression questions through `usage_compression_start`, `usage_compression_status`, `usage_compression_profile`, `usage_compression_candidates`, selected `usage_compression_candidate_detail`, and optionally `usage_compression_simulate`. Use `usage_investigate` and `usage_action_brief` as compact compatibility routers when the client needs one broad entrypoint. Use `usage_report_pack`, `usage_calls`, `usage_threads`, `usage_summary`, and `usage_call_detail` for dashboard-shaped follow-up before considering raw context.

## Remediation Recommendations

When a usage-waste investigation finds clear patterns, do not stop at "interesting." Recommend practical next actions and existing tools that could reduce future usage. Keep recommendations tied to aggregate evidence, and label speculative ideas.

- If context pressure is high, threads are long, or repeated file reads dominate, suggest Headroom if available as a follow-up tool for estimating context/headroom and deciding whether to split the thread, summarize, or start a fresh task.
- If cache ratio is low on repeated work, suggest concrete workflow fixes: keep related work in one thread, avoid unnecessary broad file reads, pin reusable project context in docs, or create a small project command/script that produces the exact aggregate needed.
- If one thread or subagent pattern dominates, suggest narrowing the task, splitting investigation from implementation, or creating a repeatable custom checklist/command so Codex does not rediscover the same facts every turn.
- If effort/model choice looks expensive, compare aggregate results by model and effort before recommending lower effort, smaller models, or explicit "use minimal reasoning unless blocked" instructions.
- If diagnostics point to missing local automation, offer to design a custom lightweight solution: a repo command, lint/test selector, dashboard report preset, support-bundle check, or Codex skill update that prevents the same waste pattern.
- Mention dashboard actions that help the user verify the fix: open Calls filtered to the expensive rows, Threads sorted by tokens, Call Investigator for a selected record, or Diagnostics Notebook for usage-drain evidence.

Phrase the final answer as "what happened, why it likely matters, what to try next, how to verify." Avoid implying an external tool is installed unless the current environment or tool registry confirms it.

## Agentic Dogfood

When the maintainer asks whether MCP/skill recommendations are getting more useful, prefer the MCP polling flow when available:

1. Call `usage_dogfood_start(privacy_mode="strict")`.
2. Poll `usage_dogfood_status(job_id)` until completed or failed.
3. Call `usage_dogfood_result(job_id)` for the compact aggregate artifact.
4. For repeated checks on unchanged data after one fresh run, call `usage_dogfood_start(refresh=False, use_cache=True, privacy_mode="strict")` and confirm `result_cache.hit`.

Use the source checkout or installed CLI only as fallback:

```bash
codex-usage-tracker dogfood-agentic --privacy-mode strict --json
```

Use it to check old and new hypothesis families, direct reports, suggested goals, investigation findings, and privacy checks. Treat it as compact QA evidence, not as a user-facing raw transcript export.

For experiment-style answers, use this structure:

- `I'd like to be able to...`
- `I will accomplish it using...`
- `I'm missing access to...`
- `My hypothesis was true/false/inconclusive because...`
- `Next tool or fix...`

## Dashboard Evidence Targets

- When an MCP result includes `dashboard_target.absolute_url`, surface **Open evidence** with that exact loopback URL.
- When `absolute_url` is absent, show `dashboard_target.relative_url` and the exact `fallback_instruction` launch guidance. Do not invent or infer a service origin.
- Never infer task-level MCP availability from a dashboard target, local readiness result, installed skill, or healthy service. Verify the current task's exposed tools separately.

## Common Workflows

- Refresh the index before answering usage questions.
- Use `usage_doctor` when setup, plugin discovery, MCP launch, dashboard output, or pricing estimates look wrong.
- Use `usage_summary` for high-level totals by date, model, effort, cwd, thread, or session.
- Use `subagent_usage(response_format="json")` for observed subagent spawn counts, role/type mix, parent-thread fan-out, subagent usage share, per-spawn usage, and descriptive direct-versus-subagent comparisons.
- An observed spawn is a distinct persisted subagent session. Agents that produced no usage event are not visible, and comparison results are descriptive rather than causal.
- Use `usage_query` for stable JSON rows filtered by date, project, model, effort, thread, pricing status, token minimums, or Codex credit minimums.
- Use `usage_status` for dashboard/index freshness, active/scoped/total row counts, latest refresh timestamp, and observed allowance windows.
- Use `usage_allowance(operation="status")` as the default Limits polling entry point. It is canonical/deduped, constant-size, reports copied clone rows excluded, and returns the next refresh or polling action.
- Use `usage_allowance(operation="series", window="weekly", range="8w")` for a finite reset-aware timeline and `usage_allowance(operation="evidence", window="weekly", range="8w", limit=50)` for latest-first bounded transitions. Treat weekly windows as primary and 5-hour windows as noisy rolling-window context.
- Use `usage_allowance(operation="analysis", execution="auto")` for persisted change evidence; if it returns a generic job handle, poll `usage_job_status(job_id, include_result=True)`.
- The old `usage_allowance_status`, `usage_allowance_series`, `usage_allowance_evidence`, `usage_allowance_analysis`, and `usage_allowance_analysis_status` names remain full-profile compatibility tools through 0.24, not the default workflow.
- Use `usage_dedupe_diagnostics` to explain copied clone rows excluded from canonical totals while preserving aggregate/source provenance.
- Treat `usage_allowance_history`, `usage_allowance_diagnostics`, and `usage_allowance_export` as compatibility or explicit offline-diagnostic surfaces, not the default Limits workflow.
- Use `usage_calls` for the same aggregate Calls table rows as the React dashboard, including pagination, filters, derived pricing status, and credit confidence.
- Use `usage_call_detail` for the aggregate Call Investigator payload for one `record_id`. Use `usage_call_context` only for explicit raw-context requests.
- Use `usage_threads` for the same aggregate Threads table rows as the dashboard.
- Use `usage_report_pack` for dashboard report cards plus compact evidence rows when the user wants less cloudy "what should I inspect?" output.
- Use the Compression Lab lifecycle for broad "look through my usage for token waste" questions: start or reuse the run, poll progress, read the profile, page candidates, inspect only selected candidate details with handles, and simulate proposed interventions.
- Use `usage_dashboard_recommendations` when the dashboard-specific recommendation payload is more useful than the older markdown-oriented recommendation report.
- Use `usage_recommendations` when the user asks what to inspect next or wants ranked action items by aggregate severity.
- Use `usage_summary` presets `today`, `last-7-days`, `by-model`, `by-cwd`, `by-thread`, and `expensive` for common requests.
- Use `usage_pricing_coverage` when the user asks whether costs are fully priced or which models use estimated or missing pricing.
- Use `usage_source_coverage` when the user asks whether parser/source provenance coverage is healthy or whether the local index is ready for deeper investigation.
- Use `session_usage` for per-call and per-turn detail for one session.
- Use `usage_call_context` for one selected model call when the user asks to load actual logged context on demand.
- Use `most_expensive_usage_calls` to identify high-token calls and aggregate efficiency signals.
- Use `privacy_mode="redacted"` or `privacy_mode="strict"` for MCP tools, or the CLI global option `--privacy-mode strict` before a subcommand, when the user plans to share dashboards, CSV, JSON, screenshots, or support bundles.
- Use `export_usage_csv` when the user wants local spreadsheet-friendly data.
- Use `update_usage_pricing_config` when the user wants cost estimates based on OpenAI-published text-token pricing. This refreshes the local pricing cache and does not send local usage data anywhere. Internal Codex labels may include explicitly marked best-guess estimates when no public pricing row exists.
- Use `init_usage_pricing_config` only when the user wants a manual local pricing template or override file.
- Codex credit estimates are aggregate-only and use bundled or locally configured Codex rate-card values. Direct model matches are exact; aliases and inferred labels are marked estimated.
- Use `init_usage_allowance_config` only when the user wants a local allowance template for manually copied 5-hour or weekly remaining usage from Codex Usage or `/status`.
- Use allowance diagnostics for questions about limit drops, weekly allowance changes, 5-hour counter weirdness, or throttling. Prefer weekly evidence, read the `nonparametric-v1` statistical evidence fields, and explain `research_readiness.ready_for_public_claim` separately from local evidence grades.

---

**Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/douglasmonsky/codex-usage-tracker/skills/codex-usage-tracker/SKILL.md`