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

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

@@ -1,6 +1,6 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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.2}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+## 0.3.2 - 2026-06-08
+
+- Make `open-dashboard` and `serve-dashboard` refresh active-session logs by default, with `--no-refresh` as the explicit cached-index mode.
+- Add a token-protected dashboard action for enabling context loading without restarting a localhost server that started with context loading off.
+
+## 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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.3.0
+Version: 0.3.2
 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?"
 
@@ -67,9 +68,11 @@ codex-usage-tracker serve-dashboard --open
 
 Use your normal Python launcher for your platform: `python3` is common on macOS/Linux, and `py` may be preferable on Windows. On macOS with Homebrew, `brew install pipx` is also fine.
 
+`serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
+
 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 +80,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).
 
@@ -192,7 +195,7 @@ codex-usage-tracker summary --preset last-7-days
 codex-usage-tracker query --since 2026-06-01 --min-credits 1
 codex-usage-tracker session <session-id>
 codex-usage-tracker export --output usage.csv
-codex-usage-tracker dashboard --open
+codex-usage-tracker open-dashboard
 codex-usage-tracker support-bundle --output ~/.codex-usage-tracker/support-bundle.json
 ```
 
@@ -204,7 +207,7 @@ The tracker stores aggregate metrics only: session ids, timestamps, local source
 
 It does **not** store prompts, assistant messages, tool output, pasted secrets, raw transcript snippets, or raw context in SQLite, CSV exports, generated dashboard HTML, or synthetic screenshots.
 
-On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can be disabled with:
+On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can start off until you enable it from the details panel:
 
 ```bash
 codex-usage-tracker serve-dashboard --no-context-api --open
@@ -237,7 +240,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.2}/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?"
 
@@ -31,9 +32,11 @@ codex-usage-tracker serve-dashboard --open
 
 Use your normal Python launcher for your platform: `python3` is common on macOS/Linux, and `py` may be preferable on Windows. On macOS with Homebrew, `brew install pipx` is also fine.
 
+`serve-dashboard` refreshes active-session usage before opening by default. Use `--no-refresh` only when you intentionally want to inspect the cached local index.
+
 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 +44,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).
 
@@ -156,7 +159,7 @@ codex-usage-tracker summary --preset last-7-days
 codex-usage-tracker query --since 2026-06-01 --min-credits 1
 codex-usage-tracker session <session-id>
 codex-usage-tracker export --output usage.csv
-codex-usage-tracker dashboard --open
+codex-usage-tracker open-dashboard
 codex-usage-tracker support-bundle --output ~/.codex-usage-tracker/support-bundle.json
 ```
 
@@ -168,7 +171,7 @@ The tracker stores aggregate metrics only: session ids, timestamps, local source
 
 It does **not** store prompts, assistant messages, tool output, pasted secrets, raw transcript snippets, or raw context in SQLite, CSV exports, generated dashboard HTML, or synthetic screenshots.
 
-On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can be disabled with:
+On-demand context loading reads a single original local JSONL file only after an explicit row action, redacts common secret patterns, caps returned text size, and can start off until you enable it from the details panel:
 
 ```bash
 codex-usage-tracker serve-dashboard --no-context-api --open
@@ -201,7 +204,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.2}/SECURITY.md

@@ -22,7 +22,7 @@ The MCP `usage_call_context` tool is disabled unless the MCP server process expl
 
 ## Localhost Dashboard Token
 
-`serve-dashboard` creates a random per-server API token and embeds it in the generated dashboard HTML for that local server session. The token is used for localhost `/api/usage` refreshes and `/api/context` requests. Treat generated active dashboard files and URLs as local-only artifacts; do not publish them or send them to someone else.
+`serve-dashboard` creates a random per-server API token and embeds it in the generated dashboard HTML for that local server session. The token is used for localhost `/api/usage` refreshes, `/api/context` requests, and runtime context-loading settings. Treat generated active dashboard files and URLs as local-only artifacts; do not publish them or send them to someone else.
 
 The dashboard server rejects non-loopback hosts and cross-origin requests. This is a local hardening measure, not a reason to expose the server on a network interface.
 

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/docs/cli-reference.md

@@ -33,11 +33,15 @@ codex-usage-tracker inspect-log ~/.codex/sessions/YYYY/MM/DD/rollout-...jsonl --
 codex-usage-tracker dashboard --open
 codex-usage-tracker dashboard --include-archived --open
 codex-usage-tracker open-dashboard
+codex-usage-tracker open-dashboard --no-refresh
 codex-usage-tracker serve-dashboard --open
+codex-usage-tracker serve-dashboard --no-refresh --open
 codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
-`serve-dashboard --context-api explicit` is the default and keeps context loading as an explicit per-row action. `serve-dashboard --no-context-api` or `--context-api disabled` serves live aggregate refresh while disabling `/api/context` entirely.
+`serve-dashboard --context-api explicit` is the default and keeps context loading as an explicit per-row action. `serve-dashboard --no-context-api` or `--context-api disabled` starts with context loading off; a token-protected button in the local details panel can enable it without restarting the server.
+
+`open-dashboard` and `serve-dashboard` refresh active-session logs before opening by default. Use `--no-refresh` only for an intentionally cached snapshot. The lower-level `dashboard` command writes from the current SQLite index and does not rescan logs.
 
 Dashboards default to active sessions only. Use `--include-archived` for an all-history static/opened dashboard, or switch the served dashboard's `History` control from `Active sessions only` to `All history` when you intentionally want archived logs scanned and included.
 

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/docs/dashboard-guide.md

@@ -35,6 +35,8 @@ codex-usage-tracker --privacy-mode strict dashboard --open
 
 Redacted mode hides raw cwd/source paths, hides Git remote labels, and hashes unnamed projects while preserving configured aliases. Strict mode also hides project-relative cwd, Git branch, and tags. The dashboard header shows the active metadata mode.
 
+`serve-dashboard` refreshes active-session logs before opening by default. Use `--no-refresh` only when you intentionally want a cached view of the existing local index.
+
 The server keeps the HTML aggregate-only and enables two live features:
 
 - `Refresh` rescans local Codex logs and updates the dashboard rows.
@@ -43,12 +45,12 @@ The server keeps the HTML aggregate-only and enables two live features:
 For a static snapshot, use:
 
 ```bash
-codex-usage-tracker dashboard --open
+codex-usage-tracker open-dashboard
 ```
 
-Static file mode can still filter, sort, and inspect aggregate call fields. It cannot refresh from logs or load raw context until you open the dashboard through `serve-dashboard`.
+Static file mode can still filter, sort, and inspect aggregate call fields. `open-dashboard` refreshes before writing the snapshot unless you pass `--no-refresh`. Static files cannot refresh from logs or load raw context after opening; use `serve-dashboard` when you want those live controls.
 
-The localhost server uses a random per-server token for refresh and context API calls, validates loopback `Host` and `Origin` headers, and can run as aggregate-only with `codex-usage-tracker serve-dashboard --no-context-api`.
+The localhost server uses a random per-server token for refresh and context API calls, validates loopback `Host` and `Origin` headers, and can start with context loading off through `codex-usage-tracker serve-dashboard --no-context-api`.
 
 ## Insights View
 
@@ -141,12 +143,12 @@ When served from localhost, the details panel includes `Load context` and `Inclu
 - `Load context` fetches a size-limited, redacted context excerpt for only that call.
 - `Include tool output` repeats the request with tool output included, still redacted and capped.
 - Raw context is not written to SQLite, CSV, or the generated dashboard HTML.
-- If the server was started with `--no-context-api`, the context buttons stay disabled and the dashboard remains aggregate-only.
+- If the server was started with `--no-context-api`, context loading starts off. Use `Enable context loading` in the details panel when you want to allow explicit row actions without restarting the dashboard server.
 
 ## Practical Workflow
 
 1. Start with `serve-dashboard --open`.
-2. Use `Refresh` after a Codex run finishes, or leave `Live` enabled while you work.
+2. Leave `Live` enabled while you work, or click `Refresh` after a Codex run finishes.
 3. Leave `History` on `Active sessions only` for current work. Switch to `All history` when you intentionally want archived sessions included in the live refresh.
 4. Optionally run `parse-allowance` with copied values from Codex Usage or `/status`, or initialize and edit `allowance.json` manually.
 5. Start in `Insights` view and review the highest-severity attention cards.

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/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,23 @@ 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. Patch release `0.3.2` made dashboard launch refresh the default and added runtime enablement for context loading:
+
+- 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`
+- GitHub Release: `https://github.com/douglasmonsky/codex-usage-tracker/releases/tag/v0.3.2`
+- 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.2}/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,12 +20,14 @@ 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.
 
 Restart Codex after plugin registration if you want Codex to discover the MCP tools in a fresh session. The localhost dashboard can run immediately.
 
+`serve-dashboard` and `open-dashboard` refresh active-session usage before opening by default. Add `--no-refresh` only when you intentionally want to inspect the cached local index without scanning logs first.
+
 ## Platform Support
 
 The CLI, SQLite index, dashboard generator, and localhost server are Python-based and are not macOS-only. CI runs the package on Ubuntu with Python 3.10, 3.11, 3.12, and 3.13.
@@ -41,7 +43,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 +56,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.
@@ -107,8 +109,8 @@ codex-usage-tracker install-plugin --python .venv/bin/python --force
 Generate a static dashboard:
 
 ```bash
-codex-usage-tracker dashboard --open
 codex-usage-tracker open-dashboard
+codex-usage-tracker open-dashboard --no-refresh
 ```
 
 Serve the dashboard with live aggregate refresh and lazy context loading:
@@ -119,6 +121,9 @@ codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
 The server binds to localhost, requires a per-server token for refresh/context endpoints, and rejects non-loopback `Host` or cross-origin `Origin` headers.
+`--no-context-api` starts context loading off; the details panel can enable it later without restarting the server.
+
+`open-dashboard` and `serve-dashboard` refresh active-session logs before opening by default. The lower-level `dashboard --open` command writes from the current SQLite index when you need a fully static file-generation step.
 
 ## Setup Checks
 

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/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.2}/docs/privacy.md

@@ -29,12 +29,14 @@ Those fields are not written to SQLite, CSV exports, generated dashboard HTML, o
 
 `usage_call_context`, `codex-usage-tracker context`, and the `serve-dashboard` context endpoint read a single source JSONL file only when explicitly requested. Returned context is redacted for common secret patterns and capped in size.
 
-The context API can be disabled:
+Dashboard context loading can start off and then be enabled from the local details panel without restarting:
 
 ```bash
 codex-usage-tracker serve-dashboard --no-context-api --open
 ```
 
+The enable action is still token-protected, localhost-only, and does not load any context until you click a row-level context action.
+
 For MCP users, `usage_call_context` is additionally disabled unless the MCP server process has this environment variable:
 
 ```bash

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "codex-usage-tracking"
-version = "0.3.0"
+version = "0.3.2"
 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.2}/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 --context-api explicit --open` so Refresh and Live can use the local API, then report the localhost URL or a brief failure. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Use `codex-usage-tracker open-dashboard` 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.2}/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 --context-api explicit --open` so Refresh, Live, load-limit, and history-scope controls can call the local API. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Keep the server running while the user is using the dashboard. Use `codex-usage-tracker open-dashboard` 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 --context-api explicit --open`. Use the source-checkout `open-dashboard` 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.2}/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@262f51960747a3eb061602e92c929684f8490adb",
 )
-RUNTIME_VERSION = "0.3.0"
+RUNTIME_VERSION = "0.3.2"
 PACKAGE_SPEC_MARKER = ".codex-usage-tracker-package-spec"
 MODULE_CHECK = (
     "import importlib.metadata; "

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

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

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/src/codex_usage_tracker/cli.py

@@ -394,8 +394,12 @@ def _add_dashboard_parsers(
     )
     open_dashboard.add_argument(
         "--refresh",
-        action="store_true",
-        help="Refresh the SQLite index before generating the dashboard",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Refresh the SQLite index before generating the dashboard. "
+            "This is the default; use --no-refresh to open the cached index only."
+        ),
     )
     open_dashboard.add_argument("--codex-home", type=Path, default=DEFAULT_CODEX_HOME)
     open_dashboard.add_argument("--json", action="store_true", dest="as_json")
@@ -419,13 +423,17 @@ def _add_dashboard_parsers(
     serve.add_argument(
         "--no-context-api",
         action="store_true",
-        help="Serve aggregate dashboard refresh only and disable /api/context.",
+        help="Start with dashboard context loading off; it can be enabled from the local dashboard.",
     )
     serve.add_argument("--open", action="store_true")
     serve.add_argument(
         "--refresh",
-        action="store_true",
-        help="Refresh the SQLite index before generating and serving the dashboard",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Refresh the SQLite index before generating and serving the dashboard. "
+            "This is the default; use --no-refresh to serve the cached index only."
+        ),
     )
     serve.add_argument("--codex-home", type=Path, default=DEFAULT_CODEX_HOME)
     serve.add_argument("--include-archived", action="store_true")

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/src/codex_usage_tracker/plugin_data/dashboard/dashboard.css

@@ -875,6 +875,11 @@
       cursor: pointer;
     }
     .context-button:hover { background: #eff6ff; }
+    .context-button:disabled {
+      cursor: not-allowed;
+      opacity: 0.62;
+      background: var(--panel);
+    }
     .context-button.secondary { color: var(--muted); }
     .context-result {
       margin-top: 12px;

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/src/codex_usage_tracker/plugin_data/dashboard/dashboard.js

@@ -1345,17 +1345,24 @@
     }
     function contextControls(row) {
       const fileMode = window.location.protocol === 'file:';
-      const apiUnavailable = !contextApiEnabled || !apiToken;
-      const disabled = fileMode || apiUnavailable ? ' disabled' : '';
+      const apiMissing = !apiToken;
+      const apiDisabled = !contextApiEnabled;
+      const disabled = fileMode || apiMissing || apiDisabled ? ' disabled' : '';
       const hint = fileMode
         ? 'Open this dashboard with codex-usage-tracker serve-dashboard to load raw context on demand.'
-        : apiUnavailable
-          ? 'Context loading is disabled for this dashboard server. Restart with --context-api explicit to enable explicit row actions.'
+        : apiMissing
+          ? 'Context loading requires a localhost dashboard API token.'
+          : apiDisabled
+            ? 'Context loading is off for this dashboard server. Enable it here to load local JSONL context on demand.'
           : 'Context is not embedded in this dashboard. Press a button to read this call from the local JSONL source.';
+      const enableButton = !fileMode && !apiMissing && apiDisabled
+        ? '<button class="context-button" type="button" data-context-enable>Enable context loading</button>'
+        : '';
       return `
         <div class="context-actions">
           <button class="context-button" type="button" data-context-load${disabled}>Load context</button>
           <button class="context-button secondary" type="button" data-context-load-output${disabled}>Include tool output</button>
+          ${enableButton}
         </div>
         <div id="contextResult" class="context-result"><p class="context-note">${escapeHtml(hint)}</p></div>
       `;
@@ -1363,8 +1370,38 @@
     function bindContextButtons(row) {
       const loadButton = detailEl.querySelector('[data-context-load]');
       const outputButton = detailEl.querySelector('[data-context-load-output]');
+      const enableButton = detailEl.querySelector('[data-context-enable]');
       if (loadButton) loadButton.addEventListener('click', () => loadContext(row, false));
       if (outputButton) outputButton.addEventListener('click', () => loadContext(row, true));
+      if (enableButton) enableButton.addEventListener('click', () => enableContextApi(row));
+    }
+    async function enableContextApi(row) {
+      const target = document.getElementById('contextResult');
+      if (!target) return;
+      target.innerHTML = '<p class="context-note">Enabling context loading for this dashboard server...</p>';
+      try {
+        const params = new URLSearchParams({ enabled: '1', _: String(Date.now()) });
+        const response = await fetch(`/api/context-settings?${params.toString()}`, {
+          headers: {
+            'Accept': 'application/json',
+            'X-Codex-Usage-Token': apiToken,
+          },
+          cache: 'no-store',
+        });
+        if (!response.ok) {
+          throw new Error(`Context settings returned HTTP ${response.status}.`);
+        }
+        const payload = await response.json();
+        if (payload.error) throw new Error(payload.error);
+        contextApiEnabled = Boolean(payload.context_api_enabled);
+        showDetail(row);
+        const nextTarget = document.getElementById('contextResult');
+        if (nextTarget && contextApiEnabled) {
+          nextTarget.innerHTML = '<p class="context-note">Context loading is enabled. Press Load context to read this call from the local JSONL source.</p>';
+        }
+      } catch (error) {
+        target.innerHTML = `<p class="context-note">${escapeHtml(error.message || String(error))}</p>`;
+      }
     }
     async function loadContext(row, includeToolOutput) {
       const target = document.getElementById('contextResult');

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2}/src/codex_usage_tracker/plugin_data/docs/dashboard-guide.html

@@ -86,8 +86,9 @@ codex-usage-tracker serve-dashboard --open</code></pre>
     <p>To tune review thresholds locally, run <code>codex-usage-tracker init-thresholds</code> and edit <code>~/.codex-usage-tracker/thresholds.json</code>. These thresholds control low-cache, high-context, high-uncached-input, large-thread, reasoning-spike, low-output, and high-cost recommendations.</p>
     <p>To tune project attribution locally, run <code>codex-usage-tracker init-projects</code> and edit <code>~/.codex-usage-tracker/projects.json</code>. The dashboard derives project name, relative cwd, branch, tags, and a hashed remote origin from aggregate <code>cwd</code> and local Git metadata when available.</p>
     <p>Before sharing screenshots or generated artifacts, put <code>--privacy-mode redacted</code> or <code>--privacy-mode strict</code> before the subcommand, such as <code>codex-usage-tracker --privacy-mode strict serve-dashboard --open</code>. Redacted mode hides raw cwd/source paths, hides Git remote labels, and hashes unnamed projects while preserving configured aliases. Strict mode also hides project-relative cwd, Git branch, and tags. The dashboard header shows the active metadata mode.</p>
-    <p>The server enables live aggregate refresh and on-demand context loading. Static file mode can still filter, sort, and inspect aggregate fields, but cannot refresh logs or load context.</p>
-    <p>The localhost server uses a random per-server token for refresh and context API calls, validates loopback <code>Host</code> and <code>Origin</code> headers, and can run as aggregate-only with <code>codex-usage-tracker serve-dashboard --no-context-api</code>.</p>
+    <p><code>serve-dashboard</code> refreshes active-session logs before opening by default. Use <code>--no-refresh</code> only when you intentionally want a cached view of the existing local index.</p>
+    <p>The server enables live aggregate refresh and on-demand context loading. Static file mode can still filter, sort, and inspect aggregate fields. <code>open-dashboard</code> refreshes before writing the snapshot unless you pass <code>--no-refresh</code>. Static files cannot refresh logs or load context after opening.</p>
+    <p>The localhost server uses a random per-server token for refresh and context API calls, validates loopback <code>Host</code> and <code>Origin</code> headers, and can start with context loading off through <code>codex-usage-tracker serve-dashboard --no-context-api</code>.</p>
 
     <h2>Insights View</h2>
     <img src="assets/dashboard-insights.png" alt="Insights view with ranked attention cards, investigation presets, and top threads by attention score.">
@@ -121,7 +122,7 @@ codex-usage-tracker serve-dashboard --open</code></pre>
 
     <h2>Details And Context</h2>
     <img src="assets/dashboard-details.png" alt="Details panel showing aggregate usage fields for a selected call.">
-    <p>The details panel shows primary cost, Codex credits, allowance impact, cache, context, pricing, and next-action signals first. It then groups thread narrative, token/pricing breakdowns, credit confidence and rate-card source metadata, collapsed raw identifiers, and source metadata. When served from localhost with the context API enabled, <code>Load context</code> fetches one redacted, size-limited source excerpt on demand. When started with <code>--no-context-api</code>, context buttons stay disabled and the dashboard remains aggregate-only.</p>
+    <p>The details panel shows primary cost, Codex credits, allowance impact, cache, context, pricing, and next-action signals first. It then groups thread narrative, token/pricing breakdowns, credit confidence and rate-card source metadata, collapsed raw identifiers, and source metadata. When served from localhost with the context API enabled, <code>Load context</code> fetches one redacted, size-limited source excerpt on demand. When started with <code>--no-context-api</code>, context loading starts off; use <code>Enable context loading</code> in the details panel when you want to allow explicit row actions without restarting the dashboard server.</p>
 
     <h2>Investigating Long Chat Growth</h2>
     <p class="note">Prompt caching helps, but cached input is not free. Long-running chats can carry a large cached prefix into later turns, so usage can climb quickly even when the visible request looks small.</p>

{codex_usage_tracking-0.3.0 → codex_usage_tracking-0.3.2/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 --context-api explicit --open` so Refresh and Live can use the local API, then report the localhost URL or a brief failure. Refresh is the default for dashboard launch commands; use `--no-refresh` only when the user explicitly asks for a cached snapshot. Use `codex-usage-tracker open-dashboard` 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.