codex-usage-tracking 0.13.0__tar.gz → 0.13.1__tar.gz

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+## 0.13.1 - 2026-06-30
+
+- Add guided usage-summary diagnostics across CLI, API, and dashboard to explain the largest aggregate drivers behind usage.
+
 ## 0.13.0 - 2026-06-30
 
 - Add first-run onboarding docs covering install, setup, live-dashboard launch, empty-dashboard troubleshooting, plugin discovery, and safe issue diagnostics.

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.13.0
+Version: 0.13.1
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/docs/cli-json-schemas.md

@@ -56,6 +56,7 @@ Tracked schema ids:
 | `codex-usage-tracker-diagnostic-file-modifications-v1` | CLI `diagnostics file-modifications --json`, dashboard server `/api/diagnostics/file-modifications` |
 | `codex-usage-tracker-diagnostic-read-productivity-v1` | CLI `diagnostics read-productivity --json`, dashboard server `/api/diagnostics/read-productivity` |
 | `codex-usage-tracker-diagnostic-concentration-v1` | CLI `diagnostics concentration --json`, dashboard server `/api/diagnostics/concentration` |
+| `codex-usage-tracker-diagnostic-guided-summary-v1` | CLI `diagnostics guided-summary --json`, dashboard server `/api/diagnostics/guided-summary` |
 | `codex-usage-tracker-diagnostic-usage-drain-v1` | CLI `diagnostics usage-drain --json`, dashboard server `/api/diagnostics/usage-drain` |
 | `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_tracking-0.13.0 → codex_usage_tracking-0.13.1}/docs/cli-reference.md

@@ -128,6 +128,7 @@ codex-usage-tracker diagnostics file-reads --refresh
 codex-usage-tracker diagnostics file-modifications --refresh
 codex-usage-tracker diagnostics read-productivity --refresh
 codex-usage-tracker diagnostics concentration --refresh
+codex-usage-tracker diagnostics guided-summary --refresh
 codex-usage-tracker diagnostics fact-calls --fact-type compaction --fact-name post_compaction
 ```
 
@@ -135,7 +136,7 @@ Diagnostics expose structured event patterns and their associated token totals.
 
 Snapshot diagnostics are persisted aggregate reports. Without `--refresh`, snapshot commands return the latest stored payload or a `missing` status. With `--refresh`, they recompute from indexed source logs and replace the stored section snapshot. Ordinary `refresh`, `open-dashboard`, and dashboard `Refresh` update usage rows only; they do not recompute diagnostic snapshots.
 
-The snapshot sections answer different questions: `overview` summarizes usage rows and aggregate token totals, `tool-output` counts functions and terminal `Original token count` coverage, `commands` keeps command roots plus bounded safe child labels, `git-interactions` counts safe Git/GitHub CLI operations and token-count coverage, `file-reads` counts reader/path activity and allocated read-output tokens, `file-modifications` counts patch modification events and safe modified-path aggregates, `read-productivity` reports later-edit correlations for matching path keys, and `concentration` shows top-N token share by source/session, cwd/project, and day.
+The snapshot sections answer different questions: `overview` summarizes usage rows and aggregate token totals, `tool-output` counts functions and terminal `Original token count` coverage, `commands` keeps command roots plus bounded safe child labels, `git-interactions` counts safe Git/GitHub CLI operations and token-count coverage, `file-reads` counts reader/path activity and allocated read-output tokens, `file-modifications` counts patch modification events and safe modified-path aggregates, `read-productivity` reports later-edit correlations for matching path keys, `concentration` shows top-N token share by source/session, cwd/project, and day, and `guided-summary` turns aggregate usage patterns into a short "what is driving usage" report.
 
 Diagnostic payloads are aggregate-only. They do not include prompts, assistant text, tool arguments, tool output, patch text, raw commands, command arguments, file contents, raw absolute paths, or JSONL fragments. Git interaction diagnostics persist only root and operation labels such as `git/status` or `gh/pr`, category counts, and token coverage; they do not persist branch names, remotes, file paths, tags, commit messages, PR titles, or release notes. File-read and file-modification diagnostics use basename-only path labels plus short irreversible hashes, read-productivity percentages are temporal correlations rather than proof that a read caused a later edit, and concentration reports use safe source/session, cwd, and day labels only.
 

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/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.13.0
+release/0.13.1
 hotfix/0.3.3
 ```
 
@@ -149,8 +149,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.13.0
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.0
+python scripts/smoke_installed_package.py --from-pypi --version 0.13.1
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.1
 ```
 
 `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.
@@ -297,7 +297,7 @@ 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.13.0 -m "codex-usage-tracker 0.13.0"
+git tag -a v0.13.1 -m "codex-usage-tracker 0.13.1"
 git push origin v0.13.0
 ```
 
@@ -307,7 +307,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. 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. Patch release `0.8.1` improves Diagnostics fact table readability with pinned fact names and sortable fact columns. Minor release `0.9.0` adds persisted diagnostic snapshots, on-demand diagnostic refresh, tool/command/file-read/concentration reports, and Diagnostics dashboard panels. Minor release `0.10.0` adds Git/GitHub CLI diagnostics, file-modification diagnostics, and derived call timing fields across the dashboard and API. Patch release `0.10.1` adds lightweight action timing to context evidence and ships the synthetic Git Interactions README screenshot. Minor release `0.11.0` adds usage-drain diagnostic reports, projected weekly credit charts, and cumulative thread cost curves. Patch release `0.11.1` improves the Diagnostics weekly projection table and stale snapshot reload controls. Patch release `0.11.2` fixes served dashboard shell hydration and hardens the synthetic source-log benchmark smoke test. Patch release `0.11.3` fixes Windows live dashboard asset MIME handling. Patch release `0.11.4` fixes large-history setup refresh failures from SQLite variable limits. Minor release `0.12.0` ships the maintainability architecture repair, dashboard diagnostics hardening, Agent Maintainer ratchets, and warning-clean test suite. Patch release `0.12.1` ships the package-domain boundary split, allowance helper split, refreshed maintainability baselines, and CLI module entrypoint fix. Minor release `0.13.0` ships adoption-hardening onboarding, first-run diagnostics, support-bundle issue guidance, and installed-wheel lifecycle smoke hardening.
+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. Patch release `0.8.1` improves Diagnostics fact table readability with pinned fact names and sortable fact columns. Minor release `0.9.0` adds persisted diagnostic snapshots, on-demand diagnostic refresh, tool/command/file-read/concentration reports, and Diagnostics dashboard panels. Minor release `0.10.0` adds Git/GitHub CLI diagnostics, file-modification diagnostics, and derived call timing fields across the dashboard and API. Patch release `0.10.1` adds lightweight action timing to context evidence and ships the synthetic Git Interactions README screenshot. Minor release `0.11.0` adds usage-drain diagnostic reports, projected weekly credit charts, and cumulative thread cost curves. Patch release `0.11.1` improves the Diagnostics weekly projection table and stale snapshot reload controls. Patch release `0.11.2` fixes served dashboard shell hydration and hardens the synthetic source-log benchmark smoke test. Patch release `0.11.3` fixes Windows live dashboard asset MIME handling. Patch release `0.11.4` fixes large-history setup refresh failures from SQLite variable limits. Minor release `0.12.0` ships the maintainability architecture repair, dashboard diagnostics hardening, Agent Maintainer ratchets, and warning-clean test suite. Patch release `0.12.1` ships the package-domain boundary split, allowance helper split, refreshed maintainability baselines, and CLI module entrypoint fix. Minor release `0.13.0` ships adoption-hardening onboarding, first-run diagnostics, support-bundle issue guidance, and installed-wheel lifecycle smoke hardening. Patch release `0.13.1` adds guided usage-summary diagnostics across CLI, API, and dashboard.
 
 - 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.13.0 → codex_usage_tracking-0.13.1}/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.13.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.13.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.13.0 && codex-usage-tracker --version`.
-- [x] Verify public pipx install path for `0.13.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.13.0 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
+- [x] Verify the current public PyPI version is visible as `0.13.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.13.1`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.13.1 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.13.1`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.13.1 && /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.13.0`.
+- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.1`.
 - [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.13.0`; 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.13.1`; 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.13.0`.
+- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.13.1`.
 - 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.13.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.13.0`.
+- 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.13.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.13.1`.
 - Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
 
 ### Known Limitations

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.13.0"
+version = "0.13.1"
 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.13.0 → codex_usage_tracking-0.13.1}/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.13.0",
+    "codex-usage-tracking==0.13.1",
 )
-RUNTIME_VERSION = "0.13.0"
+RUNTIME_VERSION = "0.13.1"
 PACKAGE_SPEC_MARKER = ".codex-usage-tracker-package-spec"
 MODULE_CHECK = (
     "import importlib.metadata; "

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/src/codex_usage_tracker/__init__.py

@@ -2,6 +2,6 @@
 
 from codex_usage_tracker.core.models import UsageEvent
 
-__version__ = "0.13.0"
+__version__ = "0.13.1"
 
 __all__ = ["UsageEvent", "__version__"]

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/src/codex_usage_tracker/cli/diagnostics.py

@@ -18,6 +18,7 @@ from codex_usage_tracker.diagnostics.snapshots import (
     build_diagnostic_file_modifications_report,
     build_diagnostic_file_reads_report,
     build_diagnostic_git_interactions_report,
+    build_diagnostic_guided_summary_report,
     build_diagnostic_overview_report,
     build_diagnostic_read_productivity_report,
     build_diagnostic_tool_output_report,
@@ -145,6 +146,7 @@ _REPORT_BUILDERS: dict[str, ReportBuilder] = {
     "file-modifications": _build_snapshot_report,
     "read-productivity": _build_snapshot_report,
     "concentration": _build_snapshot_report,
+    "guided-summary": _build_snapshot_report,
     "usage-drain": _build_usage_drain_report,
 }
 
@@ -157,4 +159,5 @@ _SNAPSHOT_REPORT_BUILDERS: dict[str, Callable[..., Any]] = {
     "file-modifications": build_diagnostic_file_modifications_report,
     "read-productivity": build_diagnostic_read_productivity_report,
     "concentration": build_diagnostic_concentration_report,
+    "guided-summary": build_diagnostic_guided_summary_report,
 }

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/src/codex_usage_tracker/cli/parser_diagnostics.py

@@ -147,6 +147,18 @@ def add_diagnostics_parser(
     )
     concentration.add_argument("--json", action="store_true", dest="as_json")
 
+    guided_summary = diagnostic_subparsers.add_parser(
+        "guided-summary",
+        help="Show plain-language aggregate usage-driver diagnostics",
+    )
+    guided_summary.add_argument("--include-archived", action="store_true")
+    guided_summary.add_argument(
+        "--refresh",
+        action="store_true",
+        help="Recompute and persist guided summary snapshot before reading it.",
+    )
+    guided_summary.add_argument("--json", action="store_true", dest="as_json")
+
     usage_drain = diagnostic_subparsers.add_parser(
         "usage-drain",
         help="Show usage-drain modeling and cumulative cost diagnostic reports",

{codex_usage_tracking-0.13.0 → codex_usage_tracking-0.13.1}/src/codex_usage_tracker/core/json_contract_diagnostics.py

@@ -136,10 +136,10 @@ DIAGNOSTIC_JSON_PAYLOAD_CONTRACTS: dict[str, dict[str, Any]] = {
             }
         },
     'codex-usage-tracker-diagnostic-concentration-v1': {
-            "required": {
-                "section": str,
-                "status": str,
-                "refreshed": bool,
+        "required": {
+            "section": str,
+            "status": str,
+            "refreshed": bool,
                 "raw_context_included": bool,
                 "snapshot": (dict, NoneType),
                 "summary": (dict, NoneType),
@@ -147,11 +147,28 @@ DIAGNOSTIC_JSON_PAYLOAD_CONTRACTS: dict[str, dict[str, Any]] = {
                 "dimensions": list,
                 "largest_impact_rows": list,
                 "privacy": dict,
-                "notes": list,
-            }
-        },
+            "notes": list,
+        }
+    },
+    'codex-usage-tracker-diagnostic-guided-summary-v1': {
+        "required": {
+            "section": str,
+            "status": str,
+            "refreshed": bool,
+            "raw_context_included": bool,
+            "snapshot": (dict, NoneType),
+            "summary": (dict, NoneType),
+            "drivers": list,
+            "top_threads": list,
+            "top_models": list,
+            "top_efforts": list,
+            "token_mix": (dict, NoneType),
+            "signals": list,
+            "notes": list,
+        }
+    },
     'codex-usage-tracker-diagnostic-usage-drain-v1': {
-            "required": {
+        "required": {
                 "section": str,
                 "status": str,
                 "refreshed": bool,