codex-usage-tracking 0.14.0__tar.gz → 0.15.0__tar.gz

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.15.0 - 2026-07-05
+
+- Make the companion plugin/skills remediation-aware for token-waste investigations, including Headroom suggestions when available, dashboard verification paths, and custom local automation ideas.
+- Fix React dashboard package verification for public release readiness, including bundled React dashboard resources in local wheel smoke coverage and refreshed synthetic Calls/Details README screenshots.
+- Harden React dashboard context evidence and diagnostics smoke tests against current row-selection and duplicate-heading behavior.
+- Recenter the README around talking with the plugin/skill about local aggregate usage, with example conversation docs for token-waste and remediation workflows.
+
+## 0.14.1 - 2026-07-04
+
+- Harden React dashboard responsive chrome, including topbar control wrapping, table containment, sticky table affordances, mobile nav polish, and refreshed synthetic dashboard screenshots.
+
 ## 0.14.0 - 2026-07-04
 
 - Make `serve-dashboard --open` prefer the React dashboard route while keeping legacy `/dashboard.html` available as a localhost fallback, and expose both URLs in `serve-dashboard --json`.

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.14.0
+Version: 0.15.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -33,6 +33,7 @@ Requires-Dist: actionlint-py>=1.7.12.24; python_version >= "3.11" and extra == "
 Requires-Dist: build>=1.2; extra == "dev"
 Requires-Dist: git-agent-ratchet>=1.3.0; python_version >= "3.11" and extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pillow>=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"
@@ -42,13 +43,12 @@ Requires-Dist: wemake-python-styleguide>=1.6.2; python_version >= "3.11" and ext
 Requires-Dist: zizmor>=1.26.1; python_version >= "3.11" and extra == "dev"
 Dynamic: license-file
 
-# Codex Usage Tracker
-
 <p align="center">
-  <a href="docs/assets/dashboard-calls.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-calls-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker React dashboard showing model-call filters, frozen call rows, and row loading controls." width="49%"></a>
-  <a href="docs/assets/dashboard-call-investigator.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-call-investigator-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker call investigator showing token accounting, cache diagnostics, and explicit evidence controls." width="49%"></a>
+ <img src="docs/assets/readme-hero.png?v=readme-hero-20260704" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
 </p>
 
+# Codex Usage Tracker
+
 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)
@@ -94,6 +94,27 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 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.`
 
+## Talk To Your Usage Data
+
+The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local aggregate index, call MCP tools, and explain what is driving usage without exposing prompts or tool output.
+
+Good starter prompts:
+
+```text
+Look through my usage for token waste and recommend what I should change.
+Find high-context, low-cache calls worth opening in the investigator.
+Which threads are draining the most, and what would reduce that next time?
+Compare model and effort usage, then suggest safer defaults.
+Open the dashboard and filter Calls to the rows behind your recommendation.
+```
+
+The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
+
+Example conversation docs:
+
+- [Token Waste Review](docs/examples/token-waste-conversation.md)
+- [Remediation Planning](docs/examples/remediation-conversation.md)
+
 ## Dashboard Preview
 
 Overview is the dashboard landing workspace: it shows recent aggregate usage, weekly remaining usage context, row loading controls, and charts that open on recent dates.
@@ -130,7 +151,7 @@ If this helped you track Codex usage, starring the repo helps others find it. Is
 
 ## Companion Skill And Plugin
 
-The dashboard is the core product surface. The Codex plugin and companion usage skill are add-ons that let Codex refresh local aggregates, call the MCP tools, and explain usage patterns conversationally after plugin discovery. Examples: [MCP And Codex Skills](docs/mcp.md).
+The dashboard is the core product surface. The Codex plugin and companion usage skills let Codex refresh local aggregates, call MCP tools, and explain usage patterns conversationally after plugin discovery. Setup and tool details: [MCP And Codex Skills](docs/mcp.md).
 
 <p align="center">
   <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=readme-drilldown" alt="Synthetic Codex plugin prompt preview showing usage dashboard and thread investigation suggestions." width="86%"></a>

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/README.md

@@ -1,10 +1,9 @@
-# Codex Usage Tracker
-
 <p align="center">
-  <a href="docs/assets/dashboard-calls.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-calls-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker React dashboard showing model-call filters, frozen call rows, and row loading controls." width="49%"></a>
-  <a href="docs/assets/dashboard-call-investigator.png?v=readme-smart-20260704"><img src="docs/assets/dashboard-call-investigator-preview.png?v=readme-smart-20260704" alt="Codex Usage Tracker call investigator showing token accounting, cache diagnostics, and explicit evidence controls." width="49%"></a>
+ <img src="docs/assets/readme-hero.png?v=readme-hero-20260704" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
 </p>
 
+# Codex Usage Tracker
+
 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)
@@ -50,6 +49,27 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 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.`
 
+## Talk To Your Usage Data
+
+The dashboard shows the evidence; the companion plugin and skills make it conversational. After `setup` and a Codex restart, ask Codex to refresh the local aggregate index, call MCP tools, and explain what is driving usage without exposing prompts or tool output.
+
+Good starter prompts:
+
+```text
+Look through my usage for token waste and recommend what I should change.
+Find high-context, low-cache calls worth opening in the investigator.
+Which threads are draining the most, and what would reduce that next time?
+Compare model and effort usage, then suggest safer defaults.
+Open the dashboard and filter Calls to the rows behind your recommendation.
+```
+
+The companion skill treats waste discovery as diagnosis plus remediation: it can point to Calls, Threads, Call Investigator, Diagnostics Notebook, Headroom when available, or a custom local command/skill/report preset Codex can build to stop repeating the same waste pattern.
+
+Example conversation docs:
+
+- [Token Waste Review](docs/examples/token-waste-conversation.md)
+- [Remediation Planning](docs/examples/remediation-conversation.md)
+
 ## Dashboard Preview
 
 Overview is the dashboard landing workspace: it shows recent aggregate usage, weekly remaining usage context, row loading controls, and charts that open on recent dates.
@@ -86,7 +106,7 @@ If this helped you track Codex usage, starring the repo helps others find it. Is
 
 ## Companion Skill And Plugin
 
-The dashboard is the core product surface. The Codex plugin and companion usage skill are add-ons that let Codex refresh local aggregates, call the MCP tools, and explain usage patterns conversationally after plugin discovery. Examples: [MCP And Codex Skills](docs/mcp.md).
+The dashboard is the core product surface. The Codex plugin and companion usage skills let Codex refresh local aggregates, call MCP tools, and explain usage patterns conversationally after plugin discovery. Setup and tool details: [MCP And Codex Skills](docs/mcp.md).
 
 <p align="center">
   <a href="docs/assets/plugin-prompts.png"><img src="docs/assets/plugin-prompts.png?v=readme-drilldown" alt="Synthetic Codex plugin prompt preview showing usage dashboard and thread investigation suggestions." width="86%"></a>

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/docs/adoption-hardening-roadmap.md

@@ -94,7 +94,7 @@ Branches:
 
 Release target:
 
-- Ship `0.15.0` when refresh behavior is explainable for both normal and large histories.
+- Fold remaining refresh-behavior hardening into the next adoption patch/minor after `0.15.0`.
 
 ## 0.16: Maintainability Ratchet
 

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/docs/development.md

@@ -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.14.0
-python scripts/smoke_installed_package.py --docker --from-pypi --version 0.14.0
+python scripts/smoke_installed_package.py --from-pypi --version 0.15.0
+python scripts/smoke_installed_package.py --docker --from-pypi --version 0.15.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.
@@ -214,6 +214,14 @@ After refreshing screenshots, copy the same files into `src/codex_usage_tracker/
 
 Do not use real session logs, real prompts, assistant text, tool output, secrets, or private data in docs or screenshots.
 
+The repository social preview artwork is generated separately:
+
+```bash
+python scripts/generate_social_preview.py
+```
+
+It writes `docs/assets/social-preview.png` and `docs/assets/readme-hero.png` at 1280x640, using exact rendered text and existing synthetic dashboard screenshots. Refresh the static downloads claim only after checking a public package-download source such as PyPI Stats.
+
 ## Large-History Benchmarking
 
 Use the synthetic benchmark script when changing SQLite filters, dashboard payload loading, or indexes:

codex_usage_tracking-0.15.0/docs/examples/remediation-conversation.md

@@ -0,0 +1,34 @@
+# Remediation Planning Conversation
+
+This is a synthetic, aggregate-only example of turning Codex Usage Tracker findings into concrete workflow changes. It is written as an example conversation doc rather than a transcript from private logs.
+
+## User
+
+Which threads are draining the most, and what can we do so this does not keep happening?
+
+## Codex With Codex Usage Tracker
+
+I refreshed the aggregate index, checked `usage_threads`, and pulled supporting Calls rows for the top thread. I did not inspect raw context.
+
+## Evidence
+
+- The top thread has repeated high-token calls after context-heavy investigation turns.
+- The Calls table shows high context-window percentage and a few low-cache rows.
+- The expensive rows are tied to repeated repository discovery and broad validation.
+
+## Recommended Remediation
+
+- Split future work into an investigation thread and an implementation thread once the plan is stable.
+- Preserve reusable findings in a short repo note or roadmap issue, then start a fresh thread from that summary.
+- Ask Codex to use a narrow validation plan first, then broaden only before release.
+- If Headroom is installed, ask it to check context pressure before continuing a long thread.
+- If the pattern repeats, have Codex build a custom local helper command or skill note that captures the exact repo facts it keeps rediscovering.
+
+## Verify
+
+Open the dashboard and check:
+
+- Threads sorted by total tokens before and after the workflow change.
+- Calls filtered to the target thread, sorted by total tokens.
+- Call Investigator for one high-pressure call.
+- Diagnostics Notebook usage-drain evidence if weekly usage remains unexpectedly high.

codex_usage_tracking-0.15.0/docs/examples/token-waste-conversation.md

@@ -0,0 +1,32 @@
+# Token Waste Review Conversation
+
+This is a synthetic, aggregate-only example of using the Codex Usage Tracker companion skill. It does not include prompts, assistant messages, tool output, pasted secrets, raw transcript text, real thread names, or real usage totals.
+
+## User
+
+Look through my usage for token waste and recommend what I should change.
+
+## Codex With Codex Usage Tracker
+
+I refreshed the local aggregate index and ranked recent calls by total tokens, context-window pressure, cache ratio, and thread totals.
+
+## Evidence
+
+- One long implementation thread accounts for most recent tokens.
+- Several calls have high input tokens with low cached input, which means repeated context was not being reused efficiently.
+- The most expensive rows cluster around broad file discovery plus full test reruns.
+
+## Likely Waste Pattern
+
+Codex is rediscovering project context and rerunning broad checks in the same workstream. The dashboard evidence to inspect next is Calls sorted by total tokens, then the top thread in Threads, then the highest-pressure record in Call Investigator.
+
+## Next Actions
+
+- Use Calls to open the top three expensive rows.
+- If Headroom is available, use it to estimate whether the thread is near context pressure before continuing.
+- Move stable project facts into docs or an `AGENTS.md` note so Codex does not need to infer them repeatedly.
+- Create a repo-specific validation command or test-selection checklist if broad checks are happening every turn.
+
+## Verify
+
+After the next few sessions, compare Threads total tokens, Calls cache ratio, and Diagnostics Notebook usage-drain evidence against the previous window.

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/docs/mcp.md

@@ -38,6 +38,7 @@ Open dashboard.
 Use my Codex Usage Tracker data to explain what drove usage this week.
 Heaviest thread?
 Thread leaderboard.
+Look through my usage for token waste and recommend fixes.
 Find low-cache or high-context calls from today and suggest what to inspect next.
 Look through my usage for token waste.
 Find calls where context got bloated.
@@ -51,6 +52,8 @@ The API skill should refresh the local index, call aggregate tools such as `usag
 
 If MCP tools are not available, the same questions can be answered through CLI JSON commands documented in [CLI And MCP JSON Schemas](cli-json-schemas.md).
 
+Waste-discovery answers should include remediation ideas when evidence supports them: dashboard rows to inspect, Headroom if available for context/headroom checks, workflow changes such as thread splitting or lower effort for routine work, and small custom local commands or skill updates Codex can build when the same waste pattern keeps recurring.
+
 The companion skill cannot read your logged-in Codex account plan, native remaining allowance, or usage from other agentic surfaces. Remaining allowance context is only as accurate as the values you manually copy into `~/.codex-usage-tracker/allowance.json`.
 
 ## Tools

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.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.14.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.14.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.14.0 && codex-usage-tracker --version`.
-- [x] Verify public pipx install path for `0.14.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.14.0 && /tmp/codex-usage-pipx-bin/codex-usage-tracker --version`.
+- [x] Verify the current public PyPI version is visible as `0.15.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.15.0`: `python -m venv /tmp/codex-usage-pypi-smoke && . /tmp/codex-usage-pypi-smoke/bin/activate && python -m pip install codex-usage-tracking==0.15.0 && codex-usage-tracker --version`.
+- [x] Verify public pipx install path for `0.15.0`: `PIPX_HOME=/tmp/codex-usage-pipx-home PIPX_BIN_DIR=/tmp/codex-usage-pipx-bin pipx install codex-usage-tracking==0.15.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.14.0`.
+- [x] Verify public PyPI package in Docker: `python scripts/smoke_installed_package.py --docker --from-pypi --version 0.15.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.14.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.15.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.14.0`.
+- Public PyPI Docker coverage is proven by `scripts/smoke_installed_package.py --docker --from-pypi --version 0.15.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.14.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.14.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.15.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.15.0`.
 - Release recovery documentation is proven by `scripts/check_release.py` required-file and docs checks.
 
 ### Known Limitations

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.14.0"
+version = "0.15.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"
@@ -47,6 +47,7 @@ dev = [
     "build>=1.2",
     "git-agent-ratchet>=1.3.0; python_version >= '3.11'",
     "mypy>=1.10",
+    "pillow>=10",
     "pytest>=8.0",
     "pytest-cov>=5.0",
     "ruff>=0.8",
@@ -73,6 +74,7 @@ where = ["src"]
   "dashboard/react/*",
   "dashboard/react/assets/*",
   "docs/*",
+  "docs/examples/*",
   "docs/assets/*",
   "rate_cards/*",
   "skills/codex-usage-api/*",

codex_usage_tracking-0.15.0/scripts/generate_social_preview.py

@@ -0,0 +1,213 @@
+"""Generate repository preview artwork.
+
+The images are built from exact rendered text and existing synthetic dashboard
+screenshots so marketing copy stays crisp and reproducible.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFilter, ImageFont
+
+ROOT = Path(__file__).resolve().parents[1]
+ASSETS = ROOT / "docs" / "assets"
+SOCIAL_OUT = ASSETS / "social-preview.png"
+README_OUT = ASSETS / "readme-hero.png"
+W, H = 1280, 640
+
+
+def font(size: int, weight: str = "regular") -> ImageFont.FreeTypeFont:
+    candidates = {
+        "regular": [
+            "/System/Library/Fonts/Supplemental/Arial.ttf",
+            "/System/Library/Fonts/Helvetica.ttc",
+        ],
+        "bold": [
+            "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+            "/System/Library/Fonts/Helvetica.ttc",
+        ],
+        "black": [
+            "/System/Library/Fonts/Supplemental/Arial Black.ttf",
+            "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+        ],
+    }[weight]
+    for candidate in candidates:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), size)
+    return ImageFont.load_default(size=size)
+
+
+def rounded_mask(size: tuple[int, int], radius: int) -> Image.Image:
+    mask = Image.new("L", size, 0)
+    draw = ImageDraw.Draw(mask)
+    draw.rounded_rectangle((0, 0, size[0] - 1, size[1] - 1), radius=radius, fill=255)
+    return mask
+
+
+def paste_rounded(base: Image.Image, image: Image.Image, xy: tuple[int, int], radius: int) -> None:
+    base.paste(image, xy, rounded_mask(image.size, radius))
+
+
+def draw_soft_shadow(base: Image.Image, box: tuple[int, int, int, int], radius: int, alpha: int = 44) -> None:
+    x0, y0, x1, y1 = box
+    shadow = Image.new("RGBA", base.size, (0, 0, 0, 0))
+    draw = ImageDraw.Draw(shadow)
+    draw.rounded_rectangle((x0, y0 + 12, x1, y1 + 18), radius=radius, fill=(15, 23, 42, alpha))
+    base.alpha_composite(shadow.filter(ImageFilter.GaussianBlur(18)))
+
+
+def cover_crop(path: Path, size: tuple[int, int], focus_y: float = 0.35) -> Image.Image:
+    src = Image.open(path).convert("RGBA")
+    target_w, target_h = size
+    scale = max(target_w / src.width, target_h / src.height)
+    resized = src.resize((int(src.width * scale), int(src.height * scale)), Image.Resampling.LANCZOS)
+    left = max(0, (resized.width - target_w) // 2)
+    top = int(max(0, resized.height - target_h) * focus_y)
+    return resized.crop((left, top, left + target_w, top + target_h))
+
+
+def draw_grid(draw: ImageDraw.ImageDraw) -> None:
+    for x in range(-80, W + 80, 40):
+        color = (214, 221, 235, 82) if x % 120 else (196, 205, 222, 110)
+        draw.line((x, 0, x + 210, H), fill=color, width=1)
+    for y in range(32, H, 42):
+        draw.line((0, y, W, y), fill=(226, 231, 240, 88), width=1)
+
+
+def make_base() -> Image.Image:
+    base = Image.new("RGBA", (W, H), (246, 248, 252, 255))
+    px = base.load()
+    if px is None:
+        raise RuntimeError("Could not access image pixels")
+    for y in range(H):
+        for x in range(W):
+            nx = x / (W - 1)
+            ny = y / (H - 1)
+            px[x, y] = (
+                int(248 - 14 * nx + 6 * ny),
+                int(250 - 10 * nx + 3 * ny),
+                int(253 - 2 * nx - 7 * ny),
+                255,
+            )
+
+    draw = ImageDraw.Draw(base)
+    draw_grid(draw)
+    draw.polygon([(820, 0), (1280, 0), (1280, 640), (730, 640)], fill=(226, 235, 255, 168))
+    draw.polygon([(982, 0), (1280, 0), (1280, 640), (890, 640)], fill=(218, 247, 238, 118))
+    return base
+
+
+def draw_dashboard_stack(base: Image.Image, *, x: int, y: int) -> None:
+    draw = ImageDraw.Draw(base)
+    card_box = (x, y, x + 536, y + 436)
+    draw_soft_shadow(base, card_box, 30, 72)
+    draw.rounded_rectangle(card_box, radius=30, fill=(255, 255, 255, 246), outline=(202, 213, 232), width=2)
+
+    overview = cover_crop(ASSETS / "dashboard-insights.png", (486, 178), 0.20)
+    calls = cover_crop(ASSETS / "dashboard-calls.png", (232, 174), 0.56)
+    investigator = cover_crop(ASSETS / "dashboard-call-investigator.png", (232, 174), 0.34)
+
+    paste_rounded(base, overview, (x + 25, y + 32), 20)
+    paste_rounded(base, calls, (x + 25, y + 232), 18)
+    paste_rounded(base, investigator, (x + 279, y + 232), 18)
+    draw.rounded_rectangle((x + 25, y + 32, x + 511, y + 210), radius=20, outline=(213, 224, 240), width=2)
+    draw.rounded_rectangle((x + 25, y + 232, x + 257, y + 406), radius=18, outline=(213, 224, 240), width=2)
+    draw.rounded_rectangle((x + 279, y + 232, x + 511, y + 406), radius=18, outline=(213, 224, 240), width=2)
+
+    draw.rounded_rectangle((x + 34, y + 44, x + 178, y + 72), radius=14, fill=(37, 99, 235, 232))
+    draw.text((x + 52, y + 49), "Overview", font=font(16, "bold"), fill=(255, 255, 255))
+    draw.rounded_rectangle((x + 34, y + 244, x + 126, y + 270), radius=13, fill=(15, 23, 42, 228))
+    draw.text((x + 51, y + 249), "Calls", font=font(15, "bold"), fill=(255, 255, 255))
+    draw.rounded_rectangle((x + 288, y + 244, x + 426, y + 270), radius=13, fill=(6, 95, 70, 224))
+    draw.text((x + 304, y + 249), "Investigator", font=font(15, "bold"), fill=(255, 255, 255))
+
+
+def draw_stat_badge(
+    draw: ImageDraw.ImageDraw,
+    xy: tuple[int, int],
+    label: str,
+    value: str,
+    fill: tuple[int, int, int],
+    outline: tuple[int, int, int],
+) -> int:
+    x, y = xy
+    label_font = font(18, "bold")
+    value_font = font(30, "black")
+    width = max(int(draw.textlength(label, font=label_font)), int(draw.textlength(value, font=value_font))) + 54
+    draw.rounded_rectangle((x, y, x + width, y + 96), radius=22, fill=fill, outline=outline, width=2)
+    draw.text((x + 26, y + 18), label, font=label_font, fill=(72, 83, 104))
+    draw.text((x + 26, y + 44), value, font=value_font, fill=(18, 28, 45))
+    return width
+
+
+def draw_title(draw: ImageDraw.ImageDraw, *, x: int, y: int) -> None:
+    draw.text((x, y), "Codex Usage", font=font(76, "black"), fill=(15, 23, 42))
+    draw.text((x, y + 76), "Tracker", font=font(86, "black"), fill=(37, 99, 235))
+    draw.text((x + 6, y + 176), "Unofficial local analytics for Codex tokens,", font=font(28, "bold"), fill=(53, 65, 85))
+    draw.text((x + 6, y + 212), "cache, threads, and spend.", font=font(28, "bold"), fill=(53, 65, 85))
+
+
+def draw_social_preview() -> Image.Image:
+    base = make_base()
+    draw = ImageDraw.Draw(base)
+    draw_dashboard_stack(base, x=662, y=82)
+
+    draw.rounded_rectangle((72, 70, 206, 112), radius=21, fill=(238, 246, 255), outline=(177, 199, 232), width=2)
+    draw.text((94, 82), "MIT License", font=font(17, "bold"), fill=(31, 55, 88))
+    draw.rounded_rectangle((224, 70, 394, 112), radius=21, fill=(238, 253, 246), outline=(161, 218, 195), width=2)
+    draw.text((246, 82), "10K+ downloads", font=font(17, "bold"), fill=(20, 83, 45))
+
+    draw_title(draw, x=72, y=150)
+
+    x = 72
+    x += draw_stat_badge(draw, (x, 414), "PACKAGE", "PyPI", (255, 255, 255), (203, 213, 225)) + 18
+    x += draw_stat_badge(draw, (x, 414), "DOWNLOADS", "10K+", (240, 253, 244), (134, 239, 172)) + 18
+    draw_stat_badge(draw, (x, 414), "LICENSE", "MIT", (239, 246, 255), (147, 197, 253))
+
+    draw.line((80, 558, 1188, 558), fill=(203, 213, 225), width=2)
+    draw.text((82, 582), "douglasmonsky/codex-usage-tracker", font=font(22, "bold"), fill=(30, 41, 59))
+    draw.text((825, 582), "Local dashboard + MCP tools", font=font(22, "bold"), fill=(71, 85, 105))
+    return base
+
+
+def draw_readme_hero() -> Image.Image:
+    base = make_base()
+    draw = ImageDraw.Draw(base)
+    draw_dashboard_stack(base, x=662, y=82)
+
+    draw.rounded_rectangle((72, 76, 324, 118), radius=21, fill=(238, 246, 255), outline=(177, 199, 232), width=2)
+    draw.text((96, 88), "Local-first Codex analytics", font=font(17, "bold"), fill=(31, 55, 88))
+
+    draw_title(draw, x=72, y=158)
+
+    bullets = [
+        "Aggregate-only dashboard",
+        "Thread, call, cache, and usage-drain views",
+        "CLI reports plus companion MCP tools",
+    ]
+    for index, text in enumerate(bullets):
+        bullet_y = 432 + index * 42
+        draw.ellipse((80, bullet_y + 8, 94, bullet_y + 22), fill=(37, 99, 235))
+        draw.text((110, bullet_y), text, font=font(24, "bold"), fill=(30, 41, 59))
+
+    draw.line((80, 580, 1188, 580), fill=(203, 213, 225), width=2)
+    draw.text((82, 602), "douglasmonsky/codex-usage-tracker", font=font(22, "bold"), fill=(30, 41, 59))
+    draw.text((832, 602), "Private logs stay local", font=font(22, "bold"), fill=(71, 85, 105))
+    return base
+
+
+def save(image: Image.Image, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    image.convert("RGB").save(path, quality=95, optimize=True)
+    print(path)
+
+
+def main() -> None:
+    save(draw_social_preview(), SOCIAL_OUT)
+    save(draw_readme_hero(), README_OUT)
+
+
+if __name__ == "__main__":
+    main()

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/scripts/smoke_installed_package.py

@@ -111,6 +111,8 @@ RESOURCE_PATHS = [
     "dashboard/locales/it.json",
     "dashboard/locales/ar.json",
     "docs/dashboard-guide.html",
+    "docs/examples/token-waste-conversation.md",
+    "docs/examples/remediation-conversation.md",
     "docs/assets/dashboard-insights.png",
     "docs/assets/dashboard-calls.png",
     "docs/assets/dashboard-calls-preview.png",

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/skills/codex-usage-api/SKILL.md

@@ -67,6 +67,17 @@ When the user asks what they can look into, offer a short menu of concrete aggre
 - "Check whether model or effort choice is wasting tokens." Use `usage_summary(group_by="model", response_format="json")`, `usage_summary(group_by="effort", response_format="json")`, and supporting `usage_calls(...)` rows.
 - "Can I share this safely?" Use `privacy_mode="strict"` and avoid `usage_call_context`.
 
+## Waste Reduction Recommendations
+
+When user asks to look for token waste, treat answer as diagnosis plus remediation. After ranking aggregate drivers, recommend concrete next steps that can reduce future usage:
+
+- Suggest Headroom when available for context/headroom estimation if evidence shows high context-window pressure, repeated large reads, or long-thread accumulation. Say "if available" unless tool registry confirms it.
+- Suggest dashboard verification steps: open top rows in Calls, inspect selected records in Call Investigator, compare Threads by total tokens, or use Diagnostics Notebook for usage-drain evidence.
+- Suggest custom solutions Codex can build when pattern repeatable: repo-specific test selector, local summary command, prompt checklist, dashboard report preset, or small script extracting exact project facts Codex keeps rediscovering.
+- Suggest workflow changes only when aggregate evidence supports them: split bloated threads, lower reasoning effort for routine edits, reuse one thread for cache-friendly related work, or start fresh thread after compacting needed state into docs.
+
+Structure recommendations as `Evidence`, `Likely waste pattern`, `Next action`, and `How to verify`. Keep privacy boundary explicit and avoid raw context unless user asks.
+
 ## Answer Style
 
 - Lead with the direct answer and key metric.

{codex_usage_tracking-0.14.0 → codex_usage_tracking-0.15.0}/skills/codex-usage-tracker/SKILL.md

@@ -41,6 +41,19 @@ When the user wants ideas, suggest concrete aggregate investigations:
 
 Route these through `usage_report_pack`, `usage_calls`, `usage_threads`, `usage_summary`, and `usage_call_detail` before considering raw context.
 
+## Remediation Recommendations
+
+When a usage-waste investigation finds clear patterns, do not stop at "interesting." Recommend practical next actions and existing tools that could reduce future usage. Keep recommendations tied to aggregate evidence, and label speculative ideas.
+
+- If context pressure is high, threads are long, or repeated file reads dominate, suggest Headroom if available as a follow-up tool for estimating context/headroom and deciding whether to split the thread, summarize, or start a fresh task.
+- If cache ratio is low on repeated work, suggest concrete workflow fixes: keep related work in one thread, avoid unnecessary broad file reads, pin reusable project context in docs, or create a small project command/script that produces the exact aggregate needed.
+- If one thread or subagent pattern dominates, suggest narrowing the task, splitting investigation from implementation, or creating a repeatable custom checklist/command so Codex does not rediscover the same facts every turn.
+- If effort/model choice looks expensive, compare aggregate results by model and effort before recommending lower effort, smaller models, or explicit "use minimal reasoning unless blocked" instructions.
+- If diagnostics point to missing local automation, offer to design a custom lightweight solution: a repo command, lint/test selector, dashboard report preset, support-bundle check, or Codex skill update that prevents the same waste pattern.
+- Mention dashboard actions that help the user verify the fix: open Calls filtered to the expensive rows, Threads sorted by tokens, Call Investigator for a selected record, or Diagnostics Notebook for usage-drain evidence.
+
+Phrase the final answer as "what happened, why it likely matters, what to try next, how to verify." Avoid implying an external tool is installed unless the current environment or tool registry confirms it.
+
 ## Common Workflows
 
 - Refresh the index before answering usage questions.