codex-usage-tracking 0.3.0__tar.gz → 0.3.1__tar.gz

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/.codex-plugin/plugin.json

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

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.3.1 - 2026-06-08
+
+- Fix packaged Codex Usage Tracker skills so dashboard-open requests start the live localhost dashboard instead of a static snapshot.
+- Mirror live-dashboard skill guidance between source-tree skills and packaged plugin-data copies so release and wheel checks stay green.
+- Use the valid explicit context API flag form, `serve-dashboard --refresh --context-api explicit --open`, for live dashboard launches.
+
 ## 0.3.0 - 2026-06-08
 
 0.3.0 is a stabilization and public-preview release for the dashboard, CLI, MCP tools, local privacy model, packaged Codex plugin, and companion usage skills. The PyPI/TestPyPI distribution name is now `codex-usage-tracking`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`, the Python import package remains `codex_usage_tracker`, and the installed CLI command remains `codex-usage-tracker`.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.3.0
+Version: 0.3.1
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -44,6 +44,7 @@ Dynamic: license-file
 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)
+[![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
 ![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
@@ -51,7 +52,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
 
-Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere.
+Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
 After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
@@ -69,7 +70,7 @@ Use your normal Python launcher for your platform: `python3` is common on macOS/
 
 Package naming: the PyPI distribution is `codex-usage-tracking`; the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
 
-Development or pre-release source install:
+Source install for development or branch testing:
 
 ```bash
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
@@ -77,7 +78,7 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 `setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
-Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard. Use https://github.com/douglasmonsky/codex-usage-tracker only if the PyPI install is unavailable.`
+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.`
 
 After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: [MCP And Codex Skills](docs/mcp.md).
 
@@ -237,7 +238,7 @@ Open a Codex session on your machine and paste this:
 
 ```text
 Install and configure Codex Usage Tracker.
-Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. If PyPI is unavailable, fall back to pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git".
+Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. Use pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git" only for branch testing or if PyPI is temporarily unavailable.
 If pipx is missing, install it with the platform's Python launcher or use a local virtual environment.
 After installation, run codex-usage-tracker setup and serve-dashboard --open.
 Verify the dashboard opens locally and tell me the dashboard URL plus whether I need to restart Codex for plugin discovery.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/README.md

@@ -8,6 +8,7 @@
 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)
+[![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
 ![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
@@ -15,7 +16,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
 
-Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere.
+Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
 After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
@@ -33,7 +34,7 @@ Use your normal Python launcher for your platform: `python3` is common on macOS/
 
 Package naming: the PyPI distribution is `codex-usage-tracking`; the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
 
-Development or pre-release source install:
+Source install for development or branch testing:
 
 ```bash
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
@@ -41,7 +42,7 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 `setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
-Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard. Use https://github.com/douglasmonsky/codex-usage-tracker only if the PyPI install is unavailable.`
+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.`
 
 After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: [MCP And Codex Skills](docs/mcp.md).
 
@@ -201,7 +202,7 @@ Open a Codex session on your machine and paste this:
 
 ```text
 Install and configure Codex Usage Tracker.
-Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. If PyPI is unavailable, fall back to pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git".
+Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. Use pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git" only for branch testing or if PyPI is temporarily unavailable.
 If pipx is missing, install it with the platform's Python launcher or use a local virtual environment.
 After installation, run codex-usage-tracker setup and serve-dashboard --open.
 Verify the dashboard opens locally and tell me the dashboard URL plus whether I need to restart Codex for plugin discovery.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/docs/development.md

@@ -12,7 +12,7 @@ python -m pip install ".[dev]" twine
 codex-usage-tracker install-plugin --python .venv/bin/python
 ```
 
-The public PyPI distribution is `codex-usage-tracking`; it installs the `codex-usage-tracker` command. The repository and import package remain `douglasmonsky/codex-usage-tracker` and `codex_usage_tracker`.
+The public PyPI distribution is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/); it installs the `codex-usage-tracker` command. The repository and import package remain `douglasmonsky/codex-usage-tracker` and `codex_usage_tracker`.
 
 ## Repo Layout
 
@@ -119,15 +119,22 @@ The release checker verifies version alignment, required public docs, packaged p
 
 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.
 
-Before running a publish job, configure pending Trusted Publishers in both services with project name `codex-usage-tracking`, owner `douglasmonsky`, repository `codex-usage-tracker`, workflow filename `publish.yml`, and the matching environment name:
+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:
+
+- 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`
+- PyPI: `https://pypi.org/project/codex-usage-tracking/`
+- TestPyPI: `https://test.pypi.org/project/codex-usage-tracking/`
+
+Before publishing a future release, confirm Trusted Publishers are still configured in both services with project name `codex-usage-tracking`, owner `douglasmonsky`, repository `codex-usage-tracker`, workflow filename `publish.yml`, and the matching environment name:
 
 - TestPyPI environment: `testpypi`
 - PyPI environment: `pypi`
 
-TestPyPI and PyPI are separate services/accounts. Configure both before publishing to both.
+TestPyPI and PyPI are separate services/accounts. Configure both before publishing to both, and keep the `pypi` GitHub environment behind manual approval.
 
 To publish to TestPyPI, run the `Publish Python package` workflow manually with `target` set to `testpypi`. The job builds once, checks the artifacts with `twine`, uploads them as workflow artifacts, then publishes the same artifacts to `https://test.pypi.org/project/codex-usage-tracking/`.
 
-To publish to PyPI, either publish a GitHub Release for the tag or manually run the workflow with `target` set to `pypi`. Keep the `pypi` GitHub environment behind manual approval. The final project URL is `https://pypi.org/project/codex-usage-tracking/`.
+To publish to PyPI, either publish a GitHub Release for the tag or manually run the workflow with `target` set to `pypi`. The final project URL is `https://pypi.org/project/codex-usage-tracking/`.
 
-PyPI and TestPyPI filenames and versions cannot be reused after upload. If a bad `0.3.0` artifact is uploaded, cut `0.3.1` instead of trying to replace it.
+PyPI and TestPyPI filenames and versions cannot be reused after upload. If a bad artifact is uploaded, cut the next patch version instead of trying to replace it.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/docs/install.md

@@ -2,7 +2,7 @@
 
 ## Recommended Install
 
-Use `pipx` so the tracker is installed as a command-line app without mixing dependencies into another project.
+Use `pipx` so the tracker is installed from PyPI as a command-line app without mixing dependencies into another project.
 
 ```bash
 python -m pip install --user pipx
@@ -20,7 +20,7 @@ Use the Python launcher that is normal for your platform:
 
 If `codex-usage-tracker` is not found immediately after `ensurepath`, open a new terminal or add the printed pipx binary directory to `PATH`.
 
-Package naming: the PyPI distribution is `codex-usage-tracking`; the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
+Package naming: the public PyPI distribution is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/); the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
 
 `setup` installs or refreshes the package-owned plugin wrapper, including MCP tools and companion Codex skills, initializes local config templates when needed, refreshes the aggregate index, runs `doctor`, prints a success/failure summary, and tells you whether Codex needs a restart for plugin discovery.
 
@@ -41,7 +41,7 @@ pipx upgrade codex-usage-tracking
 codex-usage-tracker setup
 ```
 
-For development or pre-release source installs, rerun the GitHub install with `--force`:
+For source installs used during development or branch testing, rerun the GitHub install with `--force`:
 
 ```bash
 pipx install --force "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
@@ -54,7 +54,7 @@ Open a Codex session on your machine and paste:
 
 ```text
 Install and configure Codex Usage Tracker.
-Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. If PyPI is unavailable, fall back to pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git".
+Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. Use pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git" only for branch testing or if PyPI is temporarily unavailable.
 If pipx is missing, install it with the platform's Python launcher or use a local virtual environment.
 After installation, run codex-usage-tracker setup and serve-dashboard --open.
 Verify the dashboard opens locally and tell me the dashboard URL plus whether I need to restart Codex for plugin discovery.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/docs/mcp.md

@@ -18,7 +18,9 @@ codex-usage-tracker install-plugin --python .venv/bin/python
 
 Restart Codex after registration so it can discover the plugin.
 
-Marketplace installs use the bundled MCP launcher at `skills/codex-usage-tracker/scripts/run_mcp.py`. On first MCP startup it creates a cached runtime under `~/.cache/codex-usage-tracker/mcp-runtime/` and installs the Python package from GitHub, so it does not require a `.venv` inside the plugin directory.
+Marketplace installs use the bundled MCP launcher at `skills/codex-usage-tracker/scripts/run_mcp.py`. On first MCP startup it creates a cached runtime under `~/.cache/codex-usage-tracker/mcp-runtime/` and installs the Python package from a pinned GitHub source commit, so it does not require a `.venv` inside the plugin directory.
+
+This is intentional: normal user installs come from the PyPI distribution `codex-usage-tracking`, while the plugin bootstrapper pins a reviewed repository commit so MCP startup does not accidentally track `main`.
 
 The launcher stores the GitHub package spec used for that runtime and reinstalls when the bundled package pin changes. Set `CODEX_USAGE_TRACKER_PACKAGE_SPEC` to test a different Git ref or `CODEX_USAGE_TRACKER_RUNTIME_DIR` to use a separate cache while debugging plugin startup.
 

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.3.0"
+version = "0.3.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.3.0/src/codex_usage_tracker/plugin_data → codex_usage_tracking-0.3.1}/skills/codex-usage-api/SKILL.md

@@ -17,7 +17,7 @@ The only exception is `usage_call_context`, which reads one selected record's lo
 
 ## First Steps
 
-1. For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Run `codex-usage-tracker open-dashboard --refresh` immediately, then report the opened path or a brief failure.
+1. For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Start the live localhost dashboard with `codex-usage-tracker serve-dashboard --refresh --context-api explicit --open` so Refresh and Live can use the local API, then report the localhost URL or a brief failure. Use `codex-usage-tracker open-dashboard --refresh` only for explicit static/offline snapshots or when the environment cannot keep a long-running server process alive; if you fall back, say the dashboard is static and Live requires `serve-dashboard`.
 2. For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Refresh the aggregate index, then call `usage_summary(group_by="thread", limit=10, response_format="json")`. If MCP tools are unavailable, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`.
 3. For normal usage questions, do not inspect repository files, plugin manifests, or local logs first. Start with the aggregate MCP tools. If MCP tools are unavailable, use the CLI JSON fallback below.
 4. Refresh before analysis with `refresh_usage_index` unless the user asks for a static historical snapshot. Keep archived sessions excluded unless the user explicitly asks for all history.

{codex_usage_tracking-0.3.0/src/codex_usage_tracker/plugin_data → codex_usage_tracking-0.3.1}/skills/codex-usage-tracker/SKILL.md

@@ -17,14 +17,14 @@ The only exception is `usage_call_context`, which intentionally reads one select
 
 ## Fast Paths
 
-- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Run `codex-usage-tracker open-dashboard --refresh` immediately.
+- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Start the live localhost dashboard with `codex-usage-tracker serve-dashboard --refresh --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Keep the server running while the user is using the dashboard. Use `codex-usage-tracker open-dashboard --refresh` only when the user explicitly asks for a static/offline snapshot or when the current environment cannot keep a server process running, and say that the result is static and Live requires `serve-dashboard`.
 - For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Use the tracker API: refresh the aggregate index, then rank threads with `usage_summary(group_by="thread", limit=10, response_format="json")`.
 - If MCP tools are unavailable for thread-ranking requests, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`. The summary is already ordered by `total_tokens` descending.
 - Answer thread-ranking requests directly from the summary rows. For the heaviest-thread question, lead with the first row's thread and total tokens; for leaderboard requests, show a compact ranked list.
-- If the CLI command is missing for open-dashboard requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli open-dashboard --refresh`.
+- If the CLI command is missing for dashboard-open requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli serve-dashboard --refresh --context-api explicit --open`. Use the source-checkout `open-dashboard --refresh` fallback only for static/offline snapshots or when a long-running server cannot be kept alive.
 - If the CLI command is missing for thread-ranking requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli refresh --json` and `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli summary --group-by thread --limit 10 --json`.
 - If neither command is available, say briefly that the tracker CLI is not on `PATH` and ask the user to run `codex-usage-tracker setup` or reinstall with `pipx`.
-- Keep open-dashboard narration minimal: one short progress note if needed, then the opened path or the failure. Do not narrate plugin discovery.
+- Keep dashboard-open narration minimal: one short progress note if needed, then the localhost URL, or if falling back to a static file, the file path plus a note that Live requires `serve-dashboard`. Do not narrate plugin discovery.
 
 ## Common Workflows
 

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.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",
-    "git+https://github.com/douglasmonsky/codex-usage-tracker.git@a95af5b3c421177eb133cc8322abee98e71bc434",
+    "git+https://github.com/douglasmonsky/codex-usage-tracker.git@97cd456bffaf41cbb14cd8afffcf6f37ad8a242d",
 )
-RUNTIME_VERSION = "0.3.0"
+RUNTIME_VERSION = "0.3.1"
 PACKAGE_SPEC_MARKER = ".codex-usage-tracker-package-spec"
 MODULE_CHECK = (
     "import importlib.metadata; "

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/src/codex_usage_tracker/__init__.py

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

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1/src/codex_usage_tracker/plugin_data}/skills/codex-usage-api/SKILL.md

@@ -17,7 +17,7 @@ The only exception is `usage_call_context`, which reads one selected record's lo
 
 ## First Steps
 
-1. For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Run `codex-usage-tracker open-dashboard --refresh` immediately, then report the opened path or a brief failure.
+1. For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Start the live localhost dashboard with `codex-usage-tracker serve-dashboard --refresh --context-api explicit --open` so Refresh and Live can use the local API, then report the localhost URL or a brief failure. Use `codex-usage-tracker open-dashboard --refresh` only for explicit static/offline snapshots or when the environment cannot keep a long-running server process alive; if you fall back, say the dashboard is static and Live requires `serve-dashboard`.
 2. For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Refresh the aggregate index, then call `usage_summary(group_by="thread", limit=10, response_format="json")`. If MCP tools are unavailable, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`.
 3. For normal usage questions, do not inspect repository files, plugin manifests, or local logs first. Start with the aggregate MCP tools. If MCP tools are unavailable, use the CLI JSON fallback below.
 4. Refresh before analysis with `refresh_usage_index` unless the user asks for a static historical snapshot. Keep archived sessions excluded unless the user explicitly asks for all history.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1/src/codex_usage_tracker/plugin_data}/skills/codex-usage-tracker/SKILL.md

@@ -17,14 +17,14 @@ The only exception is `usage_call_context`, which intentionally reads one select
 
 ## Fast Paths
 
-- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Run `codex-usage-tracker open-dashboard --refresh` immediately.
+- For "Open dashboard" or similar dashboard-open requests, do not inspect repository files, plugin manifests, tool registries, git status, or local logs first. Start the live localhost dashboard with `codex-usage-tracker serve-dashboard --refresh --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Keep the server running while the user is using the dashboard. Use `codex-usage-tracker open-dashboard --refresh` only when the user explicitly asks for a static/offline snapshot or when the current environment cannot keep a server process running, and say that the result is static and Live requires `serve-dashboard`.
 - For "Heaviest thread?", "Thread leaderboard", or similar thread-ranking requests, do not inspect repository files, SQLite schemas, plugin manifests, process lists, dashboard servers, or local logs manually. Use the tracker API: refresh the aggregate index, then rank threads with `usage_summary(group_by="thread", limit=10, response_format="json")`.
 - If MCP tools are unavailable for thread-ranking requests, run `codex-usage-tracker refresh --json` and `codex-usage-tracker summary --group-by thread --limit 10 --json`. The summary is already ordered by `total_tokens` descending.
 - Answer thread-ranking requests directly from the summary rows. For the heaviest-thread question, lead with the first row's thread and total tokens; for leaderboard requests, show a compact ranked list.
-- If the CLI command is missing for open-dashboard requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli open-dashboard --refresh`.
+- If the CLI command is missing for dashboard-open requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli serve-dashboard --refresh --context-api explicit --open`. Use the source-checkout `open-dashboard --refresh` fallback only for static/offline snapshots or when a long-running server cannot be kept alive.
 - If the CLI command is missing for thread-ranking requests and you are already inside the source checkout, use `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli refresh --json` and `PYTHONPATH=src .venv/bin/python -m codex_usage_tracker.cli summary --group-by thread --limit 10 --json`.
 - If neither command is available, say briefly that the tracker CLI is not on `PATH` and ask the user to run `codex-usage-tracker setup` or reinstall with `pipx`.
-- Keep open-dashboard narration minimal: one short progress note if needed, then the opened path or the failure. Do not narrate plugin discovery.
+- Keep dashboard-open narration minimal: one short progress note if needed, then the localhost URL, or if falling back to a static file, the file path plus a note that Live requires `serve-dashboard`. Do not narrate plugin discovery.
 
 ## Common Workflows
 

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/src/codex_usage_tracking.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.3.0
+Version: 0.3.1
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -44,6 +44,7 @@ Dynamic: license-file
 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)
+[![PyPI](https://img.shields.io/pypi/v/codex-usage-tracking.svg)](https://pypi.org/project/codex-usage-tracking/)
 ![Python 3.10-3.13](https://img.shields.io/badge/python-3.10--3.13-blue)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
@@ -51,7 +52,7 @@ Local-first dashboard, Codex plugin, and companion skill for understanding where
 
 Codex Usage Tracker reads the JSONL logs already written by Codex, indexes aggregate usage counters into SQLite, and gives you a dashboard, CLI, and MCP tools for investigating real usage patterns. It keeps prompts, assistant messages, tool output, pasted secrets, and raw transcript content out of SQLite, CSV exports, and generated dashboard HTML.
 
-Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere.
+Built for developers using Codex locally who want to know which threads, models, subagents, and long chats are driving usage without uploading logs anywhere. The public PyPI package is [`codex-usage-tracking`](https://pypi.org/project/codex-usage-tracking/), and it installs the `codex-usage-tracker` command.
 
 After install, you get a localhost dashboard, a local SQLite aggregate index, CLI reports, MCP tools, and a companion Codex skill for asking questions like "what drove my usage this week?"
 
@@ -69,7 +70,7 @@ Use your normal Python launcher for your platform: `python3` is common on macOS/
 
 Package naming: the PyPI distribution is `codex-usage-tracking`; the installed command is `codex-usage-tracker`; the GitHub repository remains `douglasmonsky/codex-usage-tracker`. The `codex-usage-tracker` PyPI name is not this project, so avoid similarly named packages when following these docs.
 
-Development or pre-release source install:
+Source install for development or branch testing:
 
 ```bash
 pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
@@ -77,7 +78,7 @@ pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git"
 
 `setup` installs or refreshes the local Codex plugin wrapper, initializes local config templates when needed, refreshes the aggregate index, runs `codex-usage-tracker doctor`, and tells you whether Codex needs a restart for plugin discovery.
 
-Want Codex to do it for you? Paste: `Install codex-usage-tracking with pipx, run codex-usage-tracker setup, and open the Codex Usage Tracker dashboard. Use https://github.com/douglasmonsky/codex-usage-tracker only if the PyPI install is unavailable.`
+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.`
 
 After plugin discovery, Codex can use the companion usage skill to refresh local aggregates, call the MCP tools, and explain usage patterns conversationally. Examples: [MCP And Codex Skills](docs/mcp.md).
 
@@ -237,7 +238,7 @@ Open a Codex session on your machine and paste this:
 
 ```text
 Install and configure Codex Usage Tracker.
-Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. If PyPI is unavailable, fall back to pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git".
+Install the PyPI distribution codex-usage-tracking with pipx. The installed command should be codex-usage-tracker. Use pipx install "git+https://github.com/douglasmonsky/codex-usage-tracker.git" only for branch testing or if PyPI is temporarily unavailable.
 If pipx is missing, install it with the platform's Python launcher or use a local virtual environment.
 After installation, run codex-usage-tracker setup and serve-dashboard --open.
 Verify the dashboard opens locally and tell me the dashboard URL plus whether I need to restart Codex for plugin discovery.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/tests/test_cli_release.py

@@ -20,7 +20,7 @@ def test_module_cli_version() -> None:
         env=_subprocess_env(),
     )
 
-    assert "codex-usage-tracker 0.3.0" in result.stdout
+    assert "codex-usage-tracker 0.3.1" in result.stdout
 
 
 def test_release_check_script_passes() -> None:
@@ -68,6 +68,38 @@ def test_readme_codex_usage_tracker_commands_reference_known_subcommands() -> No
     } <= documented
 
 
+def test_usage_skills_prefer_live_dashboard_for_open_requests() -> None:
+    repo_root = Path(__file__).resolve().parents[1]
+    skill_paths = [
+        repo_root / "skills" / "codex-usage-api" / "SKILL.md",
+        repo_root / "skills" / "codex-usage-tracker" / "SKILL.md",
+        repo_root
+        / "src"
+        / "codex_usage_tracker"
+        / "plugin_data"
+        / "skills"
+        / "codex-usage-api"
+        / "SKILL.md",
+        repo_root
+        / "src"
+        / "codex_usage_tracker"
+        / "plugin_data"
+        / "skills"
+        / "codex-usage-tracker"
+        / "SKILL.md",
+    ]
+
+    for skill_path in skill_paths:
+        skill_text = skill_path.read_text(encoding="utf-8")
+        live_command_index = skill_text.find("serve-dashboard --refresh --context-api explicit --open")
+        static_command_index = skill_text.find("open-dashboard --refresh")
+
+        assert live_command_index != -1, skill_path
+        assert static_command_index != -1, skill_path
+        assert live_command_index < static_command_index, skill_path
+        assert "Live requires `serve-dashboard`" in skill_text
+
+
 def test_cli_json_schema_doc_lists_tracked_contracts() -> None:
     repo_root = Path(__file__).resolve().parents[1]
     docs = (repo_root / "docs" / "cli-json-schemas.md").read_text(encoding="utf-8")

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.1}/tests/test_plugin_installer.py

@@ -34,7 +34,7 @@ def test_install_plugin_writes_generated_wrapper_and_marketplace(tmp_path: Path)
     assert result.replaced_existing is False
     assert second.replaced_existing is False
     assert manifest["name"] == "codex-usage-tracker"
-    assert manifest["version"] == "0.3.0"
+    assert manifest["version"] == "0.3.1"
     assert manifest["interface"]["defaultPrompt"][:3] == [
         "Open dashboard",
         "Heaviest thread?",