codex-usage-tracking 0.6.1__tar.gz → 0.8.0__tar.gz

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Unofficial local tracker for aggregate Codex token usage from local session logs.",
   "author": {
     "name": "Douglas Monsky"

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.8.0 - 2026-06-20
+
+- Add an aggregate Diagnostics dashboard for inspecting diagnostic facts, associated calls, token totals, and on-demand evidence without persisting raw transcript text.
+- Add diagnostic fact extraction, reporting APIs, dashboard drilldowns, sortable associated-call tables, and load-more controls for larger diagnostic result sets.
+- Add source byte offsets and context seek diagnostics so on-demand evidence loading can seek when offsets are valid and fall back safely when they are missing or stale.
+- Harden dashboard startup so visiting Diagnostics before other views load no longer prevents Calls, Threads, or Insights from hydrating.
+- Make Live refresh use the cached/indexed append path and fetch only newly visible leading rows instead of running the full manual refresh reset cycle.
+
+## 0.7.0 - 2026-06-18
+
+- Parse latest observed Codex usage snapshots from local rate-limit and token-count log events without persisting raw transcript text.
+- Store observed 5h and weekly usage snapshot fields in aggregate rows and expose a latest-observed usage summary for dashboard and API consumers.
+- Add a dashboard card for latest observed 5h and weekly usage with wording that distinguishes local observations from authoritative account limits.
+- Default the dashboard table experience to time-sorted Calls, replace the visible Signals column with Reasoning Output, and keep the Signals field out of the table for now.
+- Ignore known non-token parser events so refreshes stay focused on usage-bearing records.
+
 ## 0.6.1 - 2026-06-13
 
 - Polish the README landing screenshots with matched dashboard/investigator previews and an additional lower investigator evidence view.

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.6.1
+Version: 0.8.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -188,13 +188,13 @@ Optional allowance context:
 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).
+The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. When local Codex logs include `token_count.rate_limits`, the dashboard can show the latest observed 5-hour and weekly remaining percentages from those logs. Otherwise, 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.
+- `Insights`, `Calls`, `Threads`, and `Diagnostics` 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.
@@ -296,7 +296,7 @@ This is optional. The normal shell install above is the fastest trusted path for
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
 - Pricing and rate-card sources can change outside this project.
 - Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
-- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is shown only from local Codex `token_count.rate_limits` snapshots when present, or from copied values you configure.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
 - Plugin discovery limitations are separate from core Python CLI/dashboard support.
 - Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/README.md

@@ -150,13 +150,13 @@ Optional allowance context:
 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).
+The tracker cannot read your logged-in ChatGPT plan or live remaining usage automatically. When local Codex logs include `token_count.rate_limits`, the dashboard can show the latest observed 5-hour and weekly remaining percentages from those logs. Otherwise, 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.
+- `Insights`, `Calls`, `Threads`, and `Diagnostics` 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.
@@ -258,7 +258,7 @@ This is optional. The normal shell install above is the fastest trusted path for
 - Token counts come from Codex's logged counters; the tracker does not re-tokenize prompts.
 - Pricing and rate-card sources can change outside this project.
 - Pricing and Codex credit estimates depend on local rate data and confidence labels and are not guaranteed to match exact billing.
-- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is only available when you configure copied values.
+- Live account allowance cannot be read automatically by this local tracker; remaining 5-hour and weekly allowance is shown only from local Codex `token_count.rate_limits` snapshots when present, or from copied values you configure.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
 - Plugin discovery limitations are separate from core Python CLI/dashboard support.
 - Parent-child thread relationships are only as good as the metadata Codex logs; inferred auto-review attachments are labeled as inferred.

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/architecture.md

@@ -4,7 +4,7 @@ Codex Usage Tracker is a local sidecar app. It reads aggregate token counters fr
 
 ## Boundaries
 
-- `parser.py` converts local JSONL events into aggregate `UsageEvent` records. It also attaches metadata-only call-origin categories, archived-session flags, and conservative thread keys. It must not persist prompts, assistant text, tool output, or transcript snippets.
+- `parser.py` converts local JSONL events into aggregate `UsageEvent` records. It also attaches metadata-only call-origin categories, diagnostic facts from `diagnostic_facts.py`, archived-session flags, and conservative thread keys. It must not persist prompts, assistant text, tool output, command text, patch text, or transcript snippets.
 - `call_origin.py` owns the pure call-origin classifier and migrated-row fallback. It must not open source JSONL files; source-log reads belong in parser refresh or explicit context loading only.
 - `schema.py` owns persisted `usage_events` columns. Add columns there before changing SQLite migrations or export behavior.
 - `store.py` owns SQLite setup, refresh, rebuild, query access, persisted per-thread previous/next call links, materialized thread summaries, source-file refresh cursors, and SQL-backed live dashboard API slices. Keep filesystem scanning, database writes, SQL prefilters, counts, limits, offsets, and incremental refresh decisions here.
@@ -13,7 +13,7 @@ Codex Usage Tracker is a local sidecar app. It reads aggregate token counters fr
 - `costing.py`, `pricing_config.py`, `pricing_openai.py`, `pricing_estimates.py`, and `allowance.py` own cost, credit, rate-card, and allowance annotation. Keep estimate confidence and source metadata attached to rows.
 - `projects.py`, `threads.py`, and `recommendations.py` annotate aggregate rows with project identity, thread relationships, and actionable signals. Project privacy redaction also belongs in `projects.py` so CLI, MCP, dashboard, CSV, and support-bundle surfaces share the same behavior.
 - `dashboard.py` builds aggregate-only static dashboard payloads and writes HTML/assets. `server.py` adds localhost refresh, the compatibility `/api/usage` endpoint, SQL-backed live API slices, and explicit lazy context loading.
-- `plugin_data/dashboard/dashboard_format.js` owns dashboard formatting primitives. `dashboard_data.js` owns row payload and thread relationship helpers. `dashboard_analysis.js` owns scoring, sorting, recommendation, and thread grouping logic. `dashboard_cells.js` owns reusable table/cell HTML helpers. `dashboard_details.js` owns sidebar detail and thread narrative rendering. `dashboard_insights.js` owns insight cards and investigation preset UI. `dashboard_tables.js` owns Calls, Threads, and expanded thread-call table rendering. `dashboard_filters.js` owns date range parsing and row date matching. `dashboard_state.js` owns URL, CSV, and download state utilities. `dashboard_i18n.js`, `dashboard_payload_cache.js`, and `dashboard_tooltips.js` own localization, session aggregate cache, and fast tooltip helpers. `dashboard_call_investigator.js` owns the dedicated call drilldown surface. `dashboard.js` owns top-level DOM rendering, event handling, and API refresh orchestration.
+- `plugin_data/dashboard/dashboard_format.js` owns dashboard formatting primitives. `dashboard_data.js` owns row payload and thread relationship helpers. `dashboard_analysis.js` owns scoring, sorting, recommendation, and thread grouping logic. `dashboard_cells.js` owns reusable table/cell HTML helpers. `dashboard_details.js` owns sidebar detail and thread narrative rendering. `dashboard_insights.js` owns insight cards and investigation preset UI. `dashboard_tables.js` owns Calls, Threads, and expanded thread-call table rendering. `dashboard_diagnostics.js` owns the Diagnostics tab that consumes `/api/diagnostics/*` aggregate payloads. `dashboard_filters.js` owns date range parsing and row date matching. `dashboard_state.js` owns URL, CSV, and download state utilities. `dashboard_i18n.js`, `dashboard_payload_cache.js`, and `dashboard_tooltips.js` own localization, session aggregate cache, and fast tooltip helpers. `dashboard_call_investigator.js` owns the dedicated call drilldown surface. `dashboard.js` owns top-level DOM rendering, event handling, and API refresh orchestration.
 - `context.py` is the only normal path that reads raw log context, and it does so only for one selected record on demand with redaction and size limits. Its default quick mode omits tool output and serialized groups; full serialized JSONL group analysis is explicit.
 - `plugin_installer.py`, `.mcp.json`, `skills/`, and `scripts/check_release.py` own install and packaging behavior.
 - `scripts/benchmark_synthetic_history.py` owns generated large-history query timing and threshold enforcement for 10k, 100k, and 500k aggregate-row fixtures. Its optional `--with-source-logs` mode writes synthetic JSONL source logs to time explicit context loading and to guard normal dashboard payload assembly against source-log reads. It must stay synthetic-only and must not read real Codex logs.

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/cli-json-schemas.md

@@ -46,6 +46,7 @@ Tracked schema ids:
 | `codex-usage-tracker-summary-v1` | CLI `summary --json`, CLI `expensive --json`, MCP summary/expensive JSON |
 | `codex-usage-tracker-query-v1` | CLI `query`, MCP `usage_query(...)` |
 | `codex-usage-tracker-recommendations-v1` | CLI `recommendations --json`, MCP `usage_recommendations(response_format="json")` |
+| `codex-usage-tracker-diagnostics-v1` | CLI `diagnostics ... --json`, dashboard server `/api/diagnostics/*` |
 | `codex-usage-tracker-session-v1` | CLI `session --json`, MCP `session_usage(response_format="json")` |
 | `codex-usage-tracker-context-v1` | CLI `context`, MCP `usage_call_context` when raw context is explicitly enabled |
 | `codex-usage-tracker-context-disabled-v1` | MCP `usage_call_context` when raw context is disabled |
@@ -225,6 +226,61 @@ Schema: `codex-usage-tracker-session-v1`
 }
 ```
 
+## Diagnostics
+
+Commands:
+
+```bash
+codex-usage-tracker diagnostics summary --json
+codex-usage-tracker diagnostics facts --sort uncached --json
+codex-usage-tracker diagnostics fact-calls --fact-type compaction --fact-name post_compaction --json
+```
+
+Dashboard server API:
+
+- `/api/diagnostics/summary`
+- `/api/diagnostics/facts`
+- `/api/diagnostics/fact-calls?fact_type=compaction&fact_name=post_compaction`
+- `/api/diagnostics/compactions`
+- `/api/diagnostics/tools`
+
+Schema: `codex-usage-tracker-diagnostics-v1`
+
+```json
+{
+  "schema": "codex-usage-tracker-diagnostics-v1",
+  "view": "facts",
+  "filters": {
+    "since": null,
+    "until": null,
+    "model": null,
+    "effort": null,
+    "thread": null,
+    "min_tokens": null,
+    "fact_type": null,
+    "fact_name": null,
+    "fact_category": null,
+    "fact_group": null,
+    "include_archived": false,
+    "sort": "uncached",
+    "direction": "desc",
+    "limit": 50,
+    "offset": 0,
+    "privacy_mode": "normal"
+  },
+  "row_count": 1,
+  "total_matched_rows": 1,
+  "truncated": false,
+  "raw_context_included": false,
+  "rows": [],
+  "notes": [
+    "Associated token totals are not additive when one call has multiple diagnostic facts."
+  ]
+}
+```
+
+Diagnostics payloads report aggregate structured facts such as compaction, tool/function/MCP activity, command families, structured skill labels, search/read loops, and outcome events. They do not include prompts, assistant messages, tool arguments, tool output, patch text, raw commands, command arguments, file contents, or JSONL fragments. Token totals are associated with facts observed before a token-count row; they are not causal allocations.
+
 ## Pricing Coverage
 
 Command:

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/cli-reference.md

@@ -113,6 +113,20 @@ Useful investigations:
 - Use `expensive --limit 10` for a quick list of the highest-cost calls.
 - Use `recommendations --json` for ranked action rows and thread rollups with severity score, primary recommendation, and secondary signals.
 
+## Diagnostics
+
+```bash
+codex-usage-tracker diagnostics summary
+codex-usage-tracker diagnostics facts --sort uncached
+codex-usage-tracker diagnostics compactions
+codex-usage-tracker diagnostics tools
+codex-usage-tracker diagnostics fact-calls --fact-type compaction --fact-name post_compaction
+```
+
+Diagnostics expose structured event patterns and their associated token totals. They can show compactions, tool/function/MCP activity, safe command families, structured skill labels, patch outcomes, task completion, search/read loops, and aborted or rolled-back turns. Associated totals are not causal allocations and are not additive when one model call has multiple diagnostic facts.
+
+Diagnostic payloads are aggregate-only. They do not include prompts, assistant text, tool arguments, tool output, patch text, raw commands, command arguments, file contents, or JSONL fragments.
+
 ## JSON Queries
 
 ```bash

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/dashboard-guide.md

@@ -65,7 +65,7 @@ The localhost server uses a random per-server token for refresh and context API
 
 ![Insights view with ranked attention cards, investigation presets, and top threads by attention score.](assets/dashboard-insights.png)
 
-The dashboard opens in `Insights` view. This view is designed to answer "what needs attention?" before you start sorting tables.
+Open the `Insights` view when you want to answer "what needs attention?" before you start sorting tables.
 
 - `Needs Attention` cards rank costly threads, Codex allowance usage, low cache reuse, context bloat, unpriced usage, estimated pricing, and reasoning-output spikes from aggregate fields only.
 - `Investigation Presets` apply a view, derived filter, sort order, and explanatory caption together.
@@ -111,7 +111,7 @@ Useful interpretation notes:
 - `Cached input` and `Uncached input` are split so cache behavior is visible without storing transcript text.
 - A cost with `*` means the pricing row is marked as a best-guess estimate.
 - Codex credits are estimated from aggregate input, cached-input, and output token counters. Direct model matches use the bundled OpenAI Codex rate-card snapshot; inferred labels are marked estimated, and local credit-rate overrides are marked user-provided.
-- `Usage Remaining` is not read from the logged-in account plan. Configure `~/.codex-usage-tracker/allowance.json` with values copied from Codex Settings > Usage, the Codex Usage dashboard, or `/status` when you want current remaining allowance context.
+- `Usage observed` is not a live account query. It uses the latest local Codex `token_count.rate_limits` snapshot when present; otherwise configure `~/.codex-usage-tracker/allowance.json` with values copied from Codex Settings > Usage, the Codex Usage dashboard, or `/status` when you want current remaining allowance context.
 
 ## Threads View
 
@@ -126,7 +126,17 @@ Use `Threads` view when you want to understand a work session as a group instead
 - Expanded calls default to newest first. Click an expanded-call header such as `Time`, `Tokens`, `Cost`, or `Cache` to sort that thread's visible calls without changing the top-level Threads ranking.
 - Subagents with logged parent session ids are shown under the parent thread. Auto-review sessions without explicit parent ids may be attached by cwd and nearby activity and are marked as attached or inferred in the details.
 
-The same search, time range, confidence status, load limit, cards, and sort controls apply in `Insights`, `Calls`, and `Threads` views.
+## Diagnostics View
+
+Use `Diagnostics` view when you want to see what structured event patterns are happening and what token totals are associated with those patterns.
+
+- The tab consumes the localhost `/api/diagnostics/*` endpoints; static file dashboards show a live-API unavailable state.
+- The first table shows top diagnostic facts by associated uncached input tokens. Tool/function/MCP/command-family and compaction sections expose narrower slices of the same fact data.
+- Command diagnostics store only a command family such as `pytest`, `git`, or `unknown_command`. Skill and MCP labels are detected only when they are present as structured event metadata.
+- Click `Calls` on a fact row to load associated model calls. Call links and largest-call links open the Call Investigator, where raw context remains explicit and on demand.
+- Associated token totals are not causal allocations and are not additive when one call has multiple diagnostic facts.
+
+The same time range, model, reasoning, history scope, cards, and load controls apply in `Insights`, `Calls`, `Threads`, and `Diagnostics` views. Search, confidence, and sort controls currently scope the call/thread tables, not Diagnostics fact totals.
 
 ## Call Investigator
 
@@ -212,7 +222,7 @@ The dashboard is designed to be shareable as an aggregate report, but only after
 
 It includes:
 
-- session ids, thread names, cwd values, source file paths, timestamps, model labels, reasoning effort, token counts, cost estimates, Codex credit estimates, optional manually entered allowance windows, and derived ratios
+- session ids, thread names, cwd values, source file paths, timestamps, model labels, reasoning effort, token counts, cost estimates, Codex credit estimates, optional observed/copied allowance windows, and derived ratios
 
 It does not include:
 
@@ -222,7 +232,7 @@ The screenshots in this guide are produced from synthetic fixture data used by t
 
 Use `--privacy-mode redacted` or `--privacy-mode strict` before sharing generated dashboards, CSV exports, query JSON, or support bundles. Redacted mode removes raw cwd/source paths and hides unnamed project names behind stable hashes. Strict mode also hides project-relative cwd, branch, and tags. Configured project aliases are treated as explicit display opt-ins in both modes.
 
-Remaining 5-hour and weekly allowance is not read from Codex logs or inferred from the logged-in account plan automatically. Add `~/.codex-usage-tracker/allowance.json` only when you want the dashboard to show current copied allowance state. Local Codex logs may also omit usage from other ChatGPT agentic surfaces that share the same allowance.
+Remaining 5-hour and weekly allowance is not inferred from the logged-in account plan. When Codex writes local `token_count.rate_limits` snapshots, the dashboard can show the latest observed local-log percentages; otherwise add `~/.codex-usage-tracker/allowance.json` when you want copied allowance state. Local Codex logs may also omit usage from other ChatGPT agentic surfaces that share the same allowance.
 
 Archived sessions are excluded from dashboard payloads by default. The `All history` mode is an explicit opt-in because archived logs can make refreshes slower and can make current dashboards look inflated by older work.
 

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/development.md

@@ -38,7 +38,7 @@ fix/<issue-number>-short-description
 docs/<issue-number>-short-description
 chore/<issue-number>-short-description
 test/<issue-number>-short-description
-release/0.6.1
+release/0.8.0
 hotfix/0.3.3
 ```
 
@@ -91,7 +91,7 @@ blocked
 Recommended milestones:
 
 ```text
-0.6.1
+0.8.0
 1.0-readiness
 1.0.0
 ```
@@ -146,8 +146,8 @@ python scripts/smoke_installed_package.py --docker
 To verify the public PyPI package instead of the local checkout:
 
 ```bash
-python scripts/smoke_installed_package.py --from-pypi --version 0.6.1
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.6.1
+python scripts/smoke_installed_package.py --from-pypi --version 0.8.0
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.8.0
 ```
 
 `scripts/check_release.py` treats these public-package smoke commands as release-state claims. Keep their `--version` and `codex-usage-tracking==...` values aligned with `pyproject.toml`; the release gate fails when the docs claim a different public version. It also checks that install docs point at the real PyPI distribution, `codex-usage-tracking`, and keep the warning that `codex-usage-tracker` is a different PyPI package.
@@ -286,8 +286,8 @@ After the release branch merges, tag from updated `main`, not from an unreviewed
 ```bash
 git switch main
 git pull --ff-only
-git tag -a v0.6.1 -m "codex-usage-tracker 0.6.1"
-git push origin v0.6.1
+git tag -a v0.8.0 -m "codex-usage-tracker 0.8.0"
+git push origin v0.8.0
 ```
 
 Do not create or push release tags without maintainer approval.
@@ -296,7 +296,7 @@ Do not create or push release tags without maintainer approval.
 
 Publishing uses GitHub Actions Trusted Publishing through `.github/workflows/publish.yml`; do not upload from a local machine and do not add PyPI or TestPyPI API tokens.
 
-The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds. Patch release `0.4.1` was published by workflow dispatch from `main`; it hardened the PyPI publish workflow and checked off completed 1.0 readiness gates. Minor release `0.5.0` added dashboard localization support and initial language catalogs. Minor release `0.6.0` is the performance and call-drilldown release with SQL-backed live API slices, materialized thread summaries, faster evidence loading, and dashboard runtime module refactors. Patch release `0.6.1` aligns the final README/package screenshots and companion plugin assets.
+The first public package release, `0.3.0`, was published on June 8, 2026. Patch release `0.3.1` followed the same day to ship the live-dashboard skill launch fix. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading. Minor release `0.4.0` added Python 3.14 support, release recovery docs, stricter privacy/support-bundle regression coverage, and large-history benchmark thresholds. Patch release `0.4.1` was published by workflow dispatch from `main`; it hardened the PyPI publish workflow and checked off completed 1.0 readiness gates. Minor release `0.5.0` added dashboard localization support and initial language catalogs. Minor release `0.6.0` is the performance and call-drilldown release with SQL-backed live API slices, materialized thread summaries, faster evidence loading, and dashboard runtime module refactors. Patch release `0.6.1` aligns the final README/package screenshots and companion plugin assets. Minor release `0.7.0` adds observed usage snapshots and the latest-observed dashboard card while keeping raw evidence on demand only. Minor release `0.8.0` adds aggregate diagnostics, source-offset context seeking, and live dashboard loading hardening.
 
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.0`
 - GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.1`

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/one-dot-oh-readiness.md

@@ -24,12 +24,12 @@ Not guaranteed:
 
 ## 1. Public Install And Package Metadata
 
-- [x] Verify the current public PyPI version is visible as `0.6.1`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
-- [x] Verify public venv install for `0.6.1`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.6.1 && codex-usage-tracker --version`.
-- [x] Verify public pipx install path for `0.6.1`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.6.1 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
+- [x] Verify the current public PyPI version is visible as `0.8.0`: `python -c "import json, urllib.request; print(json.load(urllib.request.urlopen('https://pypi.org/pypi/codex-usage-tracking/json'))['info']['version'])"`.
+- [x] Verify public venv install for `0.8.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.8.0 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.8.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.8.0 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
 - [x] Verify installed package resources from a built wheel: `python scripts/smoke_installed_package.py`.
 - [x] Verify installed package resources in Linux Docker: `python scripts/smoke_installed_package.py --docker`.
-- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.6.1`.
+- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.8.0`.
 - [x] Verify PyPI metadata names remain unchanged: `python scripts/check_release.py`.
 - [x] Add Python 3.14 as an official support target after CI, package classifiers, docs, and installed-package smoke coverage were added. Docker smoke coverage uses `python:3.14-slim` by default. Track this in issue #12.
 
@@ -134,14 +134,14 @@ Not guaranteed:
 
 ## Evidence References
 
-These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.6.1`; all repo tests use synthetic or aggregate-only data.
+These references are the concrete proof behind completed checklist items. Public package smoke commands are version-specific to `0.8.0`; all repo tests use synthetic or aggregate-only data.
 
 ### Public Install And Package Metadata
 
 - Public PyPI version, public venv install, and public pipx install are proven by the exact public-install commands in section 1.
 - Built-wheel and installed-resource coverage is proven by `scripts/smoke_installed_package.py` and `tests/test_cli_release.py::test_installed_package_smoke_checks_help_for_stable_commands`.
 - Linux package-resource coverage is proven by `scripts/smoke_installed_package.py --docker`.
-- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.6.1`.
+- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.8.0`.
 - PyPI metadata, package/distribution names, package resources, source/wheel member names, Python 3.10-3.14 support metadata, CI workflow requirements, publish workflow safety text, and tracked secret patterns are proven by `scripts/check_release.py`, `scripts/check_release.py --dist`, and `tests/test_cli_release.py::test_release_check_script_passes`.
 
 ### Upgrade And Migration
@@ -219,8 +219,8 @@ These references are the concrete proof behind completed checklist items. Public
 - Publish workflow package name, Trusted Publishing, TestPyPI/PyPI job presence, event guards, no push/PR publishing, no token/password publishing, and manual PyPI main/tag preflight are proven by `scripts/check_release.py::_check_publish_workflow`.
 - The GitHub `pypi` environment gate is proven by `gh api repos/douglasmonsky/codex-usage-tracker/environments/pypi`, which reports a `required_reviewers` protection rule and `can_admins_bypass=false`.
 - Dist filename and wheel/sdist member checks are proven by `python -m build`, `python -m twine check dist/*`, and `python scripts/check_release.py --dist`.
-- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.6.1`.
-- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.6.1`.
+- TestPyPI publish process is proven by a workflow-dispatch run on `main`, followed by TestPyPI metadata and clean virtualenv install checks for `codex-usage-tracking==0.8.0`.
+- PyPI publish process is proven by a workflow-dispatch run on `main`, protected `pypi` environment approval, PyPI metadata visibility, clean virtualenv install, temporary pipx install, and Docker public-package smoke for `codex-usage-tracking==0.8.0`.
 - Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
 
 ### Known Limitations

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/pricing-and-credits.md

@@ -4,7 +4,7 @@ Codex Usage Tracker has three related but different concepts:
 
 - `Estimated Cost`: optional USD estimates from a local pricing file.
 - `Codex Credits`: calculated usage credits from aggregate token counters and Codex credit rates.
-- `Usage Remaining`: optional user-provided 5-hour and weekly allowance snapshots.
+- `Usage observed`: optional latest local-log 5-hour and weekly allowance snapshots, falling back to copied allowance config when logs do not include rate-limit snapshots.
 
 ## Cost Estimates
 
@@ -58,11 +58,11 @@ codex-usage-tracker update-rate-card
 
 The local snapshot is written to `~/.codex-usage-tracker/rate-card.json`. Each bundled rate and alias includes source URL, fetched date, tier, confidence, and alias rationale where applicable. Use `--source-file` only when you have a reviewed replacement JSON snapshot you want the tracker to validate and use.
 
-## Usage Remaining
+## Usage Observed
 
-`Usage Remaining` is different from `Codex Credits`. The tracker cannot currently read your logged-in ChatGPT plan, live remaining credits, reset windows, or usage from other agentic surfaces automatically.
+`Usage observed` is different from `Codex Credits`. The tracker cannot currently read your logged-in ChatGPT plan, live remaining credits, reset windows, or usage from other agentic surfaces automatically.
 
-A plan name such as Free, Plus, Pro, Business, or Enterprise can provide context, but it is not enough to know the current remaining allowance. The dashboard shows remaining values only when you copy them into `~/.codex-usage-tracker/allowance.json`.
+A plan name such as Free, Plus, Pro, Business, or Enterprise can provide context, but it is not enough to know the current remaining allowance. When local Codex logs include `token_count.rate_limits`, the dashboard shows the latest observed 5-hour and weekly percentages from those logs. Otherwise, the dashboard shows remaining values only when you copy them into `~/.codex-usage-tracker/allowance.json`.
 
 Enable optional allowance context:
 
@@ -87,6 +87,7 @@ Configure the usage component:
 - Pricing and rate-card sources can change outside this project. Refresh or pin local files when reports need a known source snapshot.
 - Local Codex logs may not include usage from other ChatGPT agentic surfaces that share the same allowance.
 - Live account allowance cannot be read automatically by this local tracker, and the dashboard does not infer live remaining allowance from the logged-in account plan.
+- Observed local-log snapshots may be stale until Codex records another model call, and may omit other agentic surfaces that share the same allowance.
 - Pricing can change after a report is generated. Use `pin-pricing` when you need reproducible historical cost estimates.
 - Rows with direct model/rate-card matches are more trustworthy than inferred aliases or local overrides.
 - Cost and credit calculations use aggregate counters; the tracker does not re-tokenize prompts or reconstruct usage from raw text.

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/docs/privacy.md

@@ -14,6 +14,8 @@ The local SQLite database is stored at `~/.codex-usage-tracker/usage.sqlite3` by
 - archived-session flag, conservative thread key, and adjacent aggregate record ids for dashboard navigation
 - materialized thread-level aggregate summaries for active and all-history scopes
 - source-file refresh metadata such as path, path hash, size, mtime, indexed line/byte offsets, latest aggregate record id, parser diagnostics, and last indexed time
+- observed Codex rate-limit snapshot metadata from local token-count logs, such as plan type, limit id, 5-hour/weekly used percentages, window lengths, and reset times
+- diagnostic fact labels tied to aggregate call records, such as safe event categories, payload type labels, counts, timestamps, and line ranges
 - pricing, credit, allowance, recommendation, and project metadata derived from aggregate fields
 
 ## Not Stored
@@ -31,6 +33,8 @@ Those fields are not written to SQLite, CSV exports, generated dashboard HTML, o
 
 Call-origin metadata is heuristic and confidence-labeled. It stores categories such as `user`, `codex`, or `unknown` plus a reason such as `user_message`, `tool_result`, `post_compaction`, or `agent_continuation`. It does not store the message text, tool output, compaction replacement text, or raw JSONL fragment that produced the category.
 
+Diagnostic facts follow the same aggregate-only rule. They can store safe structured labels such as `patch_applied`, `function_call_output`, `post_compaction`, MCP tool/server labels, structured skill labels, and command families such as `pytest`, `git`, or `unknown_command`, along with event counts and source line ranges. Command text may be classified in memory during parsing, but it is not persisted. Diagnostic facts do not store tool arguments, command text, command output, patch text, prompt or assistant text, file contents, raw JSONL fragments, or raw context evidence.
+
 ## On-Demand Context
 
 `usage_call_context`, `codex-usage-tracker context`, and the `serve-dashboard` context endpoint read a single source JSONL file only when explicitly requested. Returned context is redacted for common secret patterns and capped in size by default for CLI/MCP requests. The call investigator uses the same endpoint at runtime and requests quick redacted evidence for the selected call when the local context API is enabled; that still does not persist raw context into SQLite, CSV, support bundles, or generated dashboard HTML.
@@ -104,7 +108,7 @@ Cost estimates are calculated only from aggregate token fields and your local pr
 
 Codex credit estimates are calculated only from aggregate token fields and bundled or locally configured rate-card values.
 
-The optional allowance config is local and stores only the remaining percentages, reset times, or credit totals you manually enter.
+The optional allowance config is local and stores only the remaining percentages, reset times, or credit totals you manually enter. Observed rate-limit snapshots, when present in Codex token-count logs, store only structured percentages, window lengths, reset times, plan type, and limit id.
 
 ## Sharing Checklist
 

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.6.1"
+version = "0.8.0"
 description = "Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns."
 readme = "README.md"
 requires-python = ">=3.10"

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/scripts/check_release.py

@@ -120,6 +120,7 @@ REQUIRED_FILES = [
     "src/codex_usage_tracker/plugin_data/dashboard/dashboard_tooltips.js",
     "src/codex_usage_tracker/plugin_data/dashboard/dashboard_status.js",
     "src/codex_usage_tracker/plugin_data/dashboard/dashboard_events.js",
+    "src/codex_usage_tracker/plugin_data/dashboard/dashboard_diagnostics.js",
     "src/codex_usage_tracker/plugin_data/dashboard/dashboard_call_diagnostics.js",
     "src/codex_usage_tracker/plugin_data/dashboard/dashboard.js",
     "src/codex_usage_tracker/plugin_data/dashboard/dashboard_state.js",
@@ -163,6 +164,7 @@ WHEEL_REQUIRED_MEMBERS = {
     "codex_usage_tracker/plugin_data/dashboard/dashboard_tooltips.js",
     "codex_usage_tracker/plugin_data/dashboard/dashboard_status.js",
     "codex_usage_tracker/plugin_data/dashboard/dashboard_events.js",
+    "codex_usage_tracker/plugin_data/dashboard/dashboard_diagnostics.js",
     "codex_usage_tracker/plugin_data/dashboard/dashboard_call_diagnostics.js",
     "codex_usage_tracker/plugin_data/dashboard/dashboard.js",
     "codex_usage_tracker/plugin_data/dashboard/dashboard_state.js",

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/scripts/smoke_installed_package.py

@@ -46,6 +46,7 @@ CLI_HELP_SUBCOMMANDS = [
     "summary",
     "query",
     "recommendations",
+    "diagnostics",
     "session",
     "context",
     "dashboard",
@@ -86,6 +87,7 @@ RESOURCE_PATHS = [
     "dashboard/dashboard_events.js",
     "dashboard/dashboard_actions.js",
     "dashboard/dashboard_live.js",
+    "dashboard/dashboard_diagnostics.js",
     "dashboard/dashboard_call_diagnostics.js",
     "dashboard/dashboard.js",
     "dashboard/dashboard_state.js",

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/skills/codex-usage-tracker/scripts/run_mcp.py

@@ -15,9 +15,9 @@ from pathlib import Path
 
 PACKAGE_SPEC = os.environ.get(
     "CODEX_USAGE_TRACKER_PACKAGE_SPEC",
-    "codex-usage-tracking==0.6.1",
+    "codex-usage-tracking==0.8.0",
 )
-RUNTIME_VERSION = "0.6.1"
+RUNTIME_VERSION = "0.8.0"
 PACKAGE_SPEC_MARKER = ".codex-usage-tracker-package-spec"
 MODULE_CHECK = (
     "import importlib.metadata; "

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/src/codex_usage_tracker/__init__.py

@@ -2,6 +2,6 @@
 
 from codex_usage_tracker.models import UsageEvent
 
-__version__ = "0.6.1"
+__version__ = "0.8.0"
 
 __all__ = ["UsageEvent", "__version__"]

{codex_usage_tracking-0.6.1 → codex_usage_tracking-0.8.0}/src/codex_usage_tracker/cli.py

@@ -24,6 +24,11 @@ from codex_usage_tracker.api_payloads import (
 from codex_usage_tracker.cli_parser import build_parser
 from codex_usage_tracker.context import load_call_context
 from codex_usage_tracker.dashboard import generate_dashboard
+from codex_usage_tracker.diagnostic_reports import (
+    build_diagnostics_fact_calls_report,
+    build_diagnostics_facts_report,
+    build_diagnostics_summary_report,
+)
 from codex_usage_tracker.diagnostics import run_doctor
 from codex_usage_tracker.formatting import (
     format_doctor,
@@ -387,6 +392,79 @@ def _run_recommendations(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_diagnostics(args: argparse.Namespace) -> int:
+    command = args.diagnostics_command
+    if command == "summary":
+        report = build_diagnostics_summary_report(
+            db_path=args.db,
+            limit=args.limit,
+            since=args.since,
+            until=args.until,
+            model=args.model,
+            effort=args.effort,
+            thread=args.thread,
+            min_tokens=args.min_tokens,
+            fact_type=args.fact_type,
+            fact_name=args.fact_name,
+            fact_category=args.fact_category,
+            include_archived=args.include_archived,
+            sort=args.sort,
+            direction=args.direction,
+        )
+    elif command in {"facts", "compactions", "tools"}:
+        report = build_diagnostics_facts_report(
+            db_path=args.db,
+            limit=args.limit,
+            since=args.since,
+            until=args.until,
+            model=args.model,
+            effort=args.effort,
+            thread=args.thread,
+            min_tokens=args.min_tokens,
+            fact_type=_diagnostic_fact_type_filter(args),
+            fact_name=getattr(args, "fact_name", None),
+            fact_category=getattr(args, "fact_category", None),
+            include_archived=args.include_archived,
+            sort=args.sort,
+            direction=args.direction,
+            fact_group="tools" if command == "tools" else None,
+            view=command,
+        )
+    elif command == "fact-calls":
+        report = build_diagnostics_fact_calls_report(
+            db_path=args.db,
+            fact_type=args.fact_type,
+            fact_name=args.fact_name,
+            limit=args.limit,
+            offset=args.offset,
+            since=args.since,
+            until=args.until,
+            model=args.model,
+            effort=args.effort,
+            thread=args.thread,
+            min_tokens=args.min_tokens,
+            include_archived=args.include_archived,
+            sort=args.sort,
+            direction=args.direction,
+            privacy_mode=args.privacy_mode,
+        )
+    else:
+        raise ValueError(f"unknown diagnostics command: {command}")
+
+    if args.as_json:
+        _print_json(report.payload)
+        return 0
+    print(report.render())
+    return 0
+
+
+def _diagnostic_fact_type_filter(args: argparse.Namespace) -> str | None:
+    command = args.diagnostics_command
+    if command == "compactions":
+        return "compaction"
+    return getattr(args, "fact_type", None)
+
+
 def _run_session(args: argparse.Namespace) -> int:
     rows = query_session_usage(args.db, args.session_id, args.limit)
     rows = apply_project_privacy_to_rows(rows, privacy_mode=args.privacy_mode)
@@ -805,6 +883,7 @@ _COMMAND_HANDLERS = {
     "summary": _run_summary,
     "query": _run_query,
     "recommendations": _run_recommendations,
+    "diagnostics": _run_diagnostics,
     "session": _run_session,
     "context": _run_context,
     "dashboard": _run_dashboard,