codex-usage-tracking 0.3.0__tar.gz

codex_usage_tracking-0.3.0/.codex-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "codex-usage-tracker",
+  "version": "0.3.0",
+  "description": "Unofficial local tracker for aggregate Codex token usage from local session logs.",
+  "author": {
+    "name": "Douglas Monsky"
+  },
+  "homepage": "https://github.com/douglasmonsky/codex-usage-tracker",
+  "repository": "https://github.com/douglasmonsky/codex-usage-tracker",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "tokens",
+    "usage",
+    "mcp",
+    "dashboard"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Codex Usage Tracker",
+    "shortDescription": "Unofficial local aggregate token usage analytics for Codex",
+    "longDescription": "Unofficial independent project, not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. Reads local Codex session logs, aggregates exact token usage counters, and generates summaries, CSV exports, and a hoverable dashboard with optional localhost-only raw context loading.",
+    "developerName": "Douglas Monsky",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/douglasmonsky/codex-usage-tracker",
+    "privacyPolicyURL": "https://github.com/douglasmonsky/codex-usage-tracker",
+    "termsOfServiceURL": "https://github.com/douglasmonsky/codex-usage-tracker",
+    "defaultPrompt": [
+      "Open dashboard",
+      "Heaviest thread?",
+      "Thread leaderboard"
+    ],
+    "brandColor": "#2563EB",
+    "composerIcon": "./assets/icon.svg",
+    "logo": "./assets/icon.svg",
+    "screenshots": []
+  }
+}

codex_usage_tracking-0.3.0/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "codex-usage-tracker": {
+      "command": "python3",
+      "args": ["./skills/codex-usage-tracker/scripts/run_mcp.py"],
+      "cwd": ".",
+      "startup_timeout_sec": 120
+    }
+  }
+}

codex_usage_tracking-0.3.0/AGENTS.md

@@ -0,0 +1,126 @@
+# Codex Usage Tracker Instructions
+
+## Project Purpose
+
+This repo builds a local Codex plugin and dashboard that track aggregate token usage from Codex session logs.
+
+## Tech Stack
+
+- Python 3.10+
+- SQLite via the Python standard library
+- MCP Python SDK for Codex tool exposure
+- Pytest for tests
+
+## Repo Layout
+
+- `src/codex_usage_tracker/` - parser, SQLite store, reports, dashboard, CLI, and MCP server.
+- `src/codex_usage_tracker/context.py` - on-demand raw-context reader for one selected usage record.
+- `src/codex_usage_tracker/reports.py` - shared application/report services used by CLI and MCP wrappers.
+- `src/codex_usage_tracker/api_payloads.py` - shared stable JSON payload builders for CLI and MCP surfaces.
+- `src/codex_usage_tracker/schema.py` - single source of truth for persisted usage-event columns.
+- `src/codex_usage_tracker/threads.py` - thread attachment inference used by dashboard payload generation.
+- `src/codex_usage_tracker/pricing_config.py`, `pricing_openai.py`, `pricing_estimates.py`, and `costing.py` - pricing config, source parsing, estimate policy, and cost calculations behind the `pricing.py` facade.
+- `src/codex_usage_tracker/allowance.py` - Codex credit-rate and optional local allowance-window helpers.
+- `src/codex_usage_tracker/plugin_installer.py` - package-owned local Codex plugin installer.
+- `src/codex_usage_tracker/plugin_data/` - plugin assets, dashboard template/assets, local dashboard guide, screenshots, and skill files bundled into wheels.
+- `skills/codex-usage-tracker/` and `src/codex_usage_tracker/plugin_data/skills/codex-usage-tracker/` - operational Codex skill for tracker setup, summaries, dashboard generation, and MCP tools.
+- `skills/codex-usage-api/` and `src/codex_usage_tracker/plugin_data/skills/codex-usage-api/` - companion Codex skill for conversational analysis using the stable JSON API/MCP tools.
+- `src/codex_usage_tracker/server.py` - localhost dashboard server with live aggregate refresh and lazy context endpoints.
+- `~/.codex-usage-tracker/pricing.json` - optional local-only pricing config, never committed.
+- `~/.codex-usage-tracker/allowance.json` - optional local-only copied allowance state, never committed.
+- `.codex-plugin/plugin.json` - Codex plugin manifest.
+- `.mcp.json` - MCP server configuration for Codex.
+- `scripts/install_local_plugin.py` - compatibility wrapper around `codex-usage-tracker install-plugin`.
+- `scripts/check_release.py` - release-readiness checks for docs, versions, packaging, wheel contents, and tracked secret patterns.
+- `.github/workflows/ci.yml` - GitHub Actions test and package build workflow.
+- `.github/workflows/pricing-compat.yml` - scheduled/manual non-blocking live pricing parser compatibility check.
+- `docs/` - install, dashboard, CLI, pricing/credits, MCP, privacy, architecture, development, JSON-schema docs, and screenshots built from synthetic aggregate fixture data.
+- `tests/` - synthetic fixtures and unit tests.
+
+## Setup
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install ".[dev]" twine
+codex-usage-tracker install-plugin --python .venv/bin/python
+```
+
+## Validation
+
+Run the local CI gate before pushing to `main`:
+
+```bash
+python -m ruff check .
+python -m mypy
+python -m pytest
+python -m pytest --cov=codex_usage_tracker --cov-report=term-missing
+python -m compileall src
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_format.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_data.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js
+python scripts/check_release.py
+git diff --check
+rm -rf dist build src/codex_usage_tracker.egg-info src/codex_usage_tracking.egg-info
+python -m build
+python -m twine check dist/*
+python scripts/check_release.py --dist
+```
+
+Additional smoke checks for touched CLI surfaces:
+
+```bash
+python -m pytest
+python -m compileall src
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js
+python -m build
+python scripts/check_release.py --dist
+git diff --check
+codex-usage-tracker update-pricing --output /tmp/codex-usage-pricing.json
+codex-usage-tracker update-rate-card --output /tmp/codex-usage-rate-card.json
+codex-usage-tracker doctor
+codex-usage-tracker doctor --suggest-repair
+codex-usage-tracker dashboard --output /tmp/codex-usage-dashboard.html
+codex-usage-tracker serve-dashboard --help
+codex-usage-tracker init-allowance --output /tmp/codex-usage-allowance.json
+codex-usage-tracker parse-allowance --output /tmp/codex-usage-allowance.json "5h 79% 6:50 PM Weekly 33% Jun 7"
+codex-usage-tracker init-thresholds --output /tmp/codex-usage-thresholds.json
+codex-usage-tracker init-projects --output /tmp/codex-usage-projects.json
+codex-usage-tracker support-bundle --output /tmp/codex-usage-support.json
+codex-usage-tracker pricing-coverage
+codex-usage-tracker summary --preset by-subagent-role
+codex-usage-tracker expensive --limit 5
+```
+
+## Privacy Rules
+
+- Never commit real Codex session logs.
+- Never store raw prompts, assistant text, tool outputs, pasted secrets, or message snippets.
+- Raw context may be read only on demand from original local JSONL files; never persist it to SQLite, CSV, generated HTML, fixtures based on real logs, or commits.
+- Store only selected aggregate session metadata for subagents, including parent thread labels; do not persist raw session instructions or source JSON.
+- Keep fixture data synthetic.
+- Keep local SQLite databases, CSV exports, HTML dashboards, caches, and virtualenvs out of git.
+- Do not hard-code real current USD model pricing in source; refresh the local config from OpenAI's published pricing docs or use manual local overrides. Internal Codex model estimates must be explicitly marked as estimates with source and rationale metadata.
+- Source-stamped Codex credit rate-card snapshots must include source/date metadata, confidence labels, and local override support. Manually copied allowance remaining values stay in local config only.
+
+## Definition Of Done
+
+- Parser handles synthetic session logs without reading raw message content.
+- SQLite refresh is idempotent.
+- MCP tool functions return concise aggregate data.
+- Dashboard is generated from aggregate-only JSON.
+- Doctor, summary presets, dashboard, and expensive-call views work from CLI and MCP wrappers.
+- `codex-usage-tracker install-plugin` can register the installed package without relying on a source-checkout symlink.
+- `python -m codex_usage_tracker` and `codex-usage-tracker --version` both work.
+- Wheel and source distribution builds include plugin assets and the Codex skill.
+- `scripts/check_release.py --dist` passes before any public release.
+- Pricing coverage clearly separates configured, estimated, and unpriced model usage.
+- Codex credit coverage clearly separates exact rate-card matches, inferred aliases, and missing credit rates.
+- Dashboard Calls and Threads views share filters, totals, and aggregate-only hover details.
+- Dashboard usage docs are updated when the visible dashboard workflow changes, and screenshots must be generated from synthetic data only.
+- Dashboard aggregate refresh is localhost-only and keeps generated HTML aggregate-only; context loading is lazy, localhost-only, explicit, redacted, and not embedded in the static HTML payload.
+- Subagent calls preserve logged parent-session metadata, latch to parent thread labels when available, and auto-review attachment is clearly marked when inferred.
+- Tests and compile checks pass.

codex_usage_tracking-0.3.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## Unreleased
+
+## 0.3.0 - 2026-06-08
+
+0.3.0 is a stabilization and public-preview release for the dashboard, CLI, MCP tools, local privacy model, packaged Codex plugin, and companion usage skills. The PyPI/TestPyPI distribution name is now `codex-usage-tracking`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`, the Python import package remains `codex_usage_tracker`, and the installed CLI command remains `codex-usage-tracker`.
+
+- Add tested JSON contract validation for stable CLI and MCP payload schemas.
+- Add schema markers to doctor, pricing coverage, MCP dashboard/export/config, and opt-in context payloads.
+- Add ranked CLI/MCP recommendations with severity score, primary recommendation, secondary signals, and thread rollups.
+- Add offset-aware localhost dashboard usage API responses for paged aggregate-row automation.
+- Add a synthetic large-history benchmark script for 10k, 100k, and 500k aggregate-row SQLite fixtures.
+- Add focused mypy coverage for core JSON contract, recommendation, report, schema, model, and store modules.
+- Add Ruff, coverage, and dashboard JavaScript syntax checks to CI.
+- Split dashboard JavaScript helpers into formatting, data, state, and rendering/runtime assets.
+- Add issue templates for bugs, parser compatibility, pricing/allowance issues, and feature requests.
+- Expand security guidance for project metadata privacy, support bundles, and localhost dashboard tokens.
+
+## 0.2.0
+
+- Add project metadata privacy modes for dashboard, query, session, summary, CSV export, MCP, and support-bundle surfaces.
+- Add Codex credit estimates and optional local allowance-window context to the dashboard.
+- Add prominent unofficial-project disclaimers to docs, dashboard output, and plugin metadata.
+- Harden malformed token-count parsing, SQLite concurrency, MCP raw-context opt-in, pricing parser diagnostics, bundled dashboard docs, and schema migrations.
+- Fix Python 3.10 compatibility for UTC timestamps and release checks.
+- Add package-owned Codex plugin installation with `codex-usage-tracker install-plugin`.
+- Package plugin assets and the Codex skill into the Python wheel.
+- Add a companion `codex-usage-api` skill for conversational analysis through aggregate-only API/MCP data.
+- Add distribution metadata, source distribution manifest, and CI build checks.
+- Add `python -m codex_usage_tracker` support and CLI `--version` output.
+- Add release-readiness checks for version alignment, required docs, package data, built wheels, and tracked secret patterns.
+- Harden marketplace MCP runtime bootstrapping so cached runtimes refresh when the bundled package pin changes.
+- Harden local dashboard server responses with browser security headers and safer IPv6 localhost URLs.
+- Tighten the dashboard header copy, add click/keyboard row inspection, and keep detailed usage guidance out of the primary UI.
+- Keep call details sticky while scrolling and render timestamps as local human-readable date/time values.
+- Prefer non-review models in mixed thread model summaries, add fit-to-width model labels, and add a scroll-aware `Top` button.
+- Hide single-page dashboard pagination and keep multi-page controls compact in the toolbar.
+- Render fetched and refreshed timestamps as local human-readable date-times and make the call details scrollbar visible.
+- Rewrite the README around practical usage investigations, long-chat context growth, and pre-release limitations.
+- Add a screenshot-driven dashboard guide built from synthetic aggregate fixture data.
+- Preserve requested virtualenv Python paths during plugin install instead of resolving through interpreter symlinks.
+- Keep generated dashboards, SQLite databases, CSV exports, and raw Codex logs out of git.
+
+## 0.1.13
+
+- Add dashboard load limits, API limits, and pagination for larger Codex histories.

codex_usage_tracking-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for improving Codex Usage Tracker.
+
+## Local Setup
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install ".[dev]"
+```
+
+## Checks
+
+Run these before opening a pull request:
+
+```bash
+python -m ruff check .
+python -m pytest
+python -m pytest --cov=codex_usage_tracker --cov-report=term-missing
+python -m compileall src
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard.js
+node --check src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js
+python scripts/check_release.py
+python -m build
+python scripts/check_release.py --dist
+git diff --check
+```
+
+## Privacy Rules
+
+- Do not commit real Codex session logs.
+- Do not add tests or docs that include prompts, assistant messages, tool output, secrets, or private data.
+- Keep fixtures synthetic and aggregate-only.
+- Do not make normal reports persist raw transcript content. On-demand context loading must stay explicit, local, redacted, and size-limited.
+
+## Pull Requests
+
+Keep changes focused and include the verification commands you ran. For user-visible behavior changes, update `README.md` and `CHANGELOG.md`.

codex_usage_tracking-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Douglas Monsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codex_usage_tracking-0.3.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include README.md LICENSE CHANGELOG.md CONTRIBUTING.md SECURITY.md AGENTS.md .mcp.json
+recursive-include .codex-plugin *.json
+recursive-include assets *.svg
+recursive-include docs *.md *.png
+recursive-include skills *.md *.py
+recursive-include scripts *.py
+recursive-include src/codex_usage_tracker/plugin_data/assets *
+recursive-include src/codex_usage_tracker/plugin_data/dashboard *
+recursive-include src/codex_usage_tracker/plugin_data/docs *
+recursive-include src/codex_usage_tracker/plugin_data/rate_cards *
+recursive-include src/codex_usage_tracker/plugin_data/skills *
+recursive-include tests *.py

codex_usage_tracking-0.3.0/PKG-INFO

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: codex-usage-tracking
+Version: 0.3.0
+Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
+Author: Douglas Monsky
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/douglasmonsky/codex-usage-tracker
+Project-URL: Repository, https://github.com/douglasmonsky/codex-usage-tracker
+Project-URL: Issues, https://github.com/douglasmonsky/codex-usage-tracker/issues
+Project-URL: Changelog, https://github.com/douglasmonsky/codex-usage-tracker/blob/main/CHANGELOG.md
+Keywords: codex,mcp,tokens,usage,dashboard,openai,prompt-caching,cost-analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
+Dynamic: license-file
+
+# Codex Usage Tracker
+
+<p align="center">
+  <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=short-prompts" alt="Codex Usage Tracker companion prompts for opening the dashboard, finding the heaviest thread, and showing a thread leaderboard." width="49%"></a>
+  <a href="docs/assets/dashboard-calls.png"><img src="docs/assets/dashboard-calls-preview.png?v=usage-dashboard" alt="Codex Usage Tracker dashboard showing filters, usage totals, call rows, and call details." width="49%"></a>
+</p>
+
+Local-first dashboard, Codex plugin, and companion skill for understanding where your Codex tokens and usage credits are going.
+
+[![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)
+![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+> **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 into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
+
+Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere.
+
+After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
+
+## Quick Install
+
+```bash
+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.
+
+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.
+
+Development or pre-release source install:
+
+```bash
+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 aggregate 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. Use https://github.com/douglasmonsky/codex-usage-tracker only if the PyPI install is unavailable.`
+
+After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: [MCP And Codex Skills](docs/mcp.md).
+
+<p align="center">
+  <a href="docs/assets/plugin-thread-leaderboard.png"><img src="docs/assets/plugin-thread-leaderboard.png?v=thread-leaderboard" alt="Synthetic Codex chat preview showing the companion skill ranking threads by token usage after refreshing the local aggregate index." width="86%"></a>
+</p>
+
+If you only want plugin registration after installing the package:
+
+```bash
+codex-usage-tracker install-plugin
+```
+
+More install paths: [Install Guide](docs/install.md).
+
+## 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.13. It defaults to `~/.codex` for local Codex logs and `~/.codex-usage-tracker` for tracker data; pass `--codex-home` or `--db` when your local layout differs. Codex plugin discovery depends on Codex's local plugin directories on your machine, so run `codex-usage-tracker doctor` after setup if plugin registration does not appear in Codex.
+
+## Dashboard Preview
+
+The Calls table is the main investigation surface: filter, sort, inspect details, and export the exact aggregate rows you are looking at.
+
+![Calls view showing filters, totals, the model-call table, and the details panel.](docs/assets/dashboard-calls.png?v=aa16502)
+
+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 in chronological order.](docs/assets/dashboard-threads.png?v=3cd7338)
+
+The details panel keeps the primary cost, cache, context, allowance, and pricing signals visible before raw identifiers.
+
+![Details panel showing aggregate fields for the selected usage row.](docs/assets/dashboard-details.png?v=84cf6dd)
+
+Insights still gives a fast triage layer for costly threads, low cache reuse, context bloat, and pricing gaps.
+
+![Insights view with ranked Needs Attention cards, investigation presets, and top threads by attention score.](docs/assets/dashboard-insights.png?v=4a40e4f)
+
+The dashboard screenshots use synthetic aggregate fixture data, and the companion prompt and chat previews are synthetic. They do not contain prompts from local logs, assistant responses, tool output, real thread names, real usage totals, or real Codex session content. See the [Dashboard Guide](docs/dashboard-guide.md) for the full walkthrough.
+
+If this helped you track Codex usage, starring the repo helps others find it. Issues and feature requests are welcome.
+
+## Why This Exists
+
+Codex can quietly burn usage through long-running chats, low cache reuse, reasoning spikes, spawned subagents, and auto-review passes. This tool turns the aggregate counters already on your machine into an insight-first dashboard and scriptable local APIs.
+
+Use it to answer:
+
+- Which threads used the most tokens, estimated cost, or Codex credits?
+- Are long chats bloating because of accumulated context?
+- Which model or reasoning effort is driving usage?
+- Are subagents or auto-review passes adding unexpected cost?
+- Which calls have low cache reuse, high context pressure, reasoning spikes, or pricing gaps?
+- Which projects, project tags, or active directories are consuming the most usage?
+- What should Codex inspect next using the companion usage skill?
+
+## Long Chats Can Bloat Fast
+
+Prompt caching helps, but cached input is not the same as no input. Long threads can accumulate a large cached context, and each new turn may still include cached input plus fresh uncached input, output tokens, reasoning output, and tool-related context.
+
+The dashboard makes that pattern visible with:
+
+- `Cached input`
+- `Uncached input`
+- `Session cumulative`
+- `Context use`
+- `Cache ratio`
+
+Practical takeaway: when old context is no longer useful, starting a fresh thread can be more efficient than dragging a large cached history forward. That is not a rule for every task, but it is one of the clearest usage patterns the tracker is designed to reveal.
+
+## First Useful Workflow
+
+```bash
+codex-usage-tracker update-pricing
+codex-usage-tracker update-rate-card
+codex-usage-tracker setup
+codex-usage-tracker serve-dashboard --open
+```
+
+Then:
+
+1. Leave `Live` enabled while working, or click `Refresh` after a Codex run finishes.
+2. Start in `Insights` and scan the `Needs Attention` cards.
+3. Use `Time` presets or calendar fields to focus on today, this week, the last 7 days, this month, or a custom range.
+4. Use investigation presets for highest-cost threads, highest-credit calls, context bloat, cache misses, pricing gaps, or estimated-price review.
+5. Open `Threads` to see how a conversation grew and whether subagent or auto-review work attached to it.
+6. Hover or click rows to inspect aggregate fields in `Call Details`.
+7. Use `Load context` only when aggregate fields are not enough; context is fetched on demand from the local source JSONL and is not saved into SQLite or the dashboard.
+
+Optional allowance context:
+
+```bash
+codex-usage-tracker parse-allowance "5h 79% 6:50 PM Weekly 33% Jun 7"
+```
+
+The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. Allowance values are only as accurate as the values you manually copy from Codex Settings, `/status`, or another trusted usage display. Details: [Pricing, Credits, And Allowance](docs/pricing-and-credits.md).
+
+## What It Includes
+
+- Local SQLite index at `~/.codex-usage-tracker/usage.sqlite3`.
+- Static dashboard generation plus localhost live refresh.
+- `Insights`, `Calls`, and `Threads` dashboard views.
+- Active-only dashboards by default, with an explicit `All history` toggle for archived sessions.
+- CLI summaries, queries, CSV export, dashboard generation, doctor checks, and support bundles.
+- MCP tools for Codex sessions that want to query local usage data.
+- Companion Codex skills for operational setup and conversational usage analysis.
+- Optional local pricing, Codex credit, allowance, threshold, project alias, and privacy-mode configuration.
+
+## Common Commands
+
+```bash
+codex-usage-tracker summary --preset last-7-days
+codex-usage-tracker query --since 2026-06-01 --min-credits 1
+codex-usage-tracker session <session-id>
+codex-usage-tracker export --output usage.csv
+codex-usage-tracker dashboard --open
+codex-usage-tracker support-bundle --output ~/.codex-usage-tracker/support-bundle.json
+```
+
+Full command reference: [CLI Reference](docs/cli-reference.md).
+
+## Data Privacy
+
+The tracker stores aggregate metrics only: session ids, timestamps, local source paths, thread labels, cwd/project metadata, model labels, reasoning effort, token counters, pricing/credit annotations, and derived ratios.
+
+It does **not** store prompts, assistant messages, tool output, pasted secrets, raw transcript snippets, or raw context in SQLite, CSV exports, generated dashboard HTML, or synthetic screenshots.
+
+On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can be disabled with:
+
+```bash
+codex-usage-tracker serve-dashboard --no-context-api --open
+```
+
+For shared artifacts, use:
+
+```bash
+codex-usage-tracker --privacy-mode redacted dashboard --open
+codex-usage-tracker --privacy-mode strict export --output usage-redacted.csv
+```
+
+Full model: [Privacy Guide](docs/privacy.md).
+
+## Documentation
+
+- [Install Guide](docs/install.md)
+- [Dashboard Guide](docs/dashboard-guide.md)
+- [CLI Reference](docs/cli-reference.md)
+- [Pricing, Credits, And Allowance](docs/pricing-and-credits.md)
+- [MCP And Codex Skills](docs/mcp.md)
+- [Privacy Guide](docs/privacy.md)
+- [Architecture](docs/architecture.md)
+- [CLI And MCP JSON Schemas](docs/cli-json-schemas.md)
+- [Development And Release](docs/development.md)
+
+## Codex-Assisted Install
+
+Open a Codex session on your machine and paste this:
+
+```text
+Install and configure Codex Usage Tracker.
+Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. If PyPI is unavailable, fall back to pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git".
+If pipx is missing, install it with the platform's Python launcher or use a local virtual environment.
+After installation, run codex-usage-tracker setup and serve-dashboard --open.
+Verify the dashboard opens locally and tell me the dashboard URL plus whether I need to restart Codex for plugin discovery.
+```
+
+This is optional. The normal shell install above is the fastest trusted path for most users.
+
+## Current Limitations
+
+- This is a sidecar dashboard and plugin, not a native Codex chat overlay.
+- Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
+- Pricing and Codex credit estimates depend on local rate data and confidence labels.
+- Remaining 5-hour and weekly allowance is not read automatically from the logged-in account.
+- Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
+- Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.
+
+## Roadmap
+
+- Improve the `Set limits` flow with a paste/import experience for 5-hour and weekly allowance snapshots.
+- Track allowance snapshot history so local Codex credits can be compared against visible remaining-usage changes over time.
+- Clarify top-card token accounting by showing output tokens and reasoning output as a subset instead of implying all token cards add together.
+- Add more insight presets for cache drift, context growth, subagent-heavy workflows, and pricing/credit confidence gaps.
+- Keep the allowance provider boundary ready for an official usage or allowance API if one becomes available.
+- Continue reducing setup friction for pipx installs, local plugin discovery, and Codex companion skill usage.
+
+## Development
+
+```bash
+git clone https://github.com/douglasmonsky/codex-usage-tracker.git
+cd codex-usage-tracker
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install ".[dev]"
+python -m pytest
+```
+
+Run the full local CI gate before pushing to `main`. See [Development And Release](docs/development.md).