codex-usage-tracking 0.16.0__tar.gz → 0.17.0__tar.gz

{codex_usage_tracking-0.16.0 → codex_usage_tracking-0.17.0}/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-usage-tracker",
-  "version": "0.16.0",
-  "description": "Unofficial local tracker for aggregate Codex token usage from local session logs.",
+  "version": "0.17.0",
+  "description": "Unofficial local Codex usage dashboard and MCP diagnostics from local session logs.",
   "author": {
     "name": "Douglas Monsky"
   },
@@ -19,8 +19,8 @@
   "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Codex Usage Tracker",
-    "shortDescription": "Unofficial local aggregate token usage analytics for Codex",
-    "longDescription": "Unofficial independent project, not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. Reads local Codex session logs, aggregates exact token usage counters, and generates summaries, CSV exports, and a hoverable dashboard with optional localhost-only raw context loading.",
+    "shortDescription": "Local Codex usage dashboard, MCP diagnostics, and token-waste investigations",
+    "longDescription": "Unofficial independent project, not made by, affiliated with, endorsed by, sponsored by, or supported by OpenAI. Reads local Codex session logs to power a local dashboard, MCP tools, allowance diagnostics, token-waste investigations, and shareable aggregate reports without uploading logs.",
     "developerName": "Douglas Monsky",
     "category": "Productivity",
     "capabilities": [
@@ -33,8 +33,9 @@
     "termsOfServiceURL": "https://github.com/douglasmonsky/codex-usage-tracker",
     "defaultPrompt": [
       "Open dashboard",
-      "Heaviest thread?",
-      "Thread leaderboard"
+      "Look through my usage for token waste",
+      "Suggest usage investigations",
+      "Check whether my weekly allowance changed"
     ],
     "brandColor": "#2563EB",
     "composerIcon": "./assets/icon.svg",

{codex_usage_tracking-0.16.0 → codex_usage_tracking-0.17.0}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## Unreleased
 
+## 0.17.0 - 2026-07-08
+
+- Add agentic MCP investigation tools for hypothesis-driven usage diagnostics, compact evidence briefs, and actionable recommendation reports.
+- Add repeated file rediscovery, shell churn, and large low-output usage diagnostics to identify avoidable local workflow waste.
+- Improve bundled skill guidance so Codex can route vague usage questions into concrete tracker endpoints, Headroom suggestions, and custom remediation ideas.
+- Add async dogfood progress polling and warm result caching so longer usage investigations can report progress and rerun faster.
+- Speed up content indexing with incremental append metadata, parallel source parsing, and batched FTS rebuilds.
+- Add dashboard refresh progress bars, no-cap paged loading, loaded-call metrics, token breakdowns, persisted loading preferences, and restored usage-drain chart data.
+
+## 0.16.2 - 2026-07-08
+
+- Restore Usage Drain, Investigator Workbench, Reports, and related dashboard charts by deriving shared usage-drain series from loaded aggregate rows again.
+- Keep sparse line charts expanded to their panel width so low-point datasets do not collapse into the left edge.
+
+## 0.16.1 - 2026-07-08
+
+- Add async refresh progress polling and dashboard progress bars for long all-row loads.
+- Speed up local content index refreshes with batched writes and parallel source extraction.
+- Load uncapped dashboard rows in finite pages so no-cap mode stays responsive on large histories.
+- Show loaded-call counts and call-level token breakdowns on Overview metric cards.
+- Restore session row/history loading preferences after browser refresh without storing large row payloads.
+
 ## 0.16.0 - 2026-07-07
 
 - Add allowance intelligence foundation with normalized allowance history, evidence-graded change diagnostics, local evidence exports, and API/MCP report surfaces for weekly-vs-5-hour usage analysis.

{codex_usage_tracking-0.16.0 → codex_usage_tracking-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-usage-tracking
-Version: 0.16.0
+Version: 0.17.0
 Summary: Unofficial local Codex plugin and dashboard for investigating aggregate token usage, costs, caching, and thread patterns.
 Author: Douglas Monsky
 License-Expression: MIT
@@ -44,7 +44,7 @@ Requires-Dist: zizmor>=1.26.1; python_version >= "3.11" and extra == "dev"
 Dynamic: license-file
 
 <p align="center">
- <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%">
+ <img src="docs/assets/readme-hero-2.png?v=readme-hero-20260708" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
 </p>
 
 # Codex Usage Tracker

{codex_usage_tracking-0.16.0 → codex_usage_tracking-0.17.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
- <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%">
+ <img src="docs/assets/readme-hero-2.png?v=readme-hero-20260708" alt="Codex Usage Tracker local-first analytics dashboard preview with overview, calls, and investigator surfaces." width="100%">
 </p>
 
 # Codex Usage Tracker

codex_usage_tracking-0.17.0/docs/agentic-briefing-and-dogfood-roadmap.md

@@ -0,0 +1,187 @@
+# Agentic Briefing And Dogfood Roadmap
+
+This roadmap follows the agentic MCP and hypothesis-testing hardening work merged through
+PR #114. The current backend can already suggest investigations, test hypotheses, inspect
+large low-output calls, identify shell churn, rank repeated file rediscovery, and evaluate
+allowance-change evidence. This phase is about making that flow repeatable, easier for
+agents to use correctly, and more action-oriented for users.
+
+Product stance stays unchanged:
+
+- Local-first and unofficial.
+- Aggregate/shareable evidence by default.
+- No raw prompts, raw tool output, full paths, raw commands, or transcript snippets unless
+  the user explicitly asks for deeper local content inspection.
+- Dashboard UI is not the source of truth for this phase; backend/MCP payloads are.
+- Recommendation language must separate exact facts, estimates, missing access, and next
+  verification steps.
+
+## Why This Phase Exists
+
+Dogfooding the improved MCP flow surfaced two needs:
+
+- The project needs a repeatable local experiment harness so future changes can be checked
+  against the same old and new hypotheses instead of relying on ad hoc terminal snippets.
+- The bundled skill/plugin guidance should teach agents the new investigation sequence and
+  explain newer report concepts such as `unclassified_shell_script`.
+- The MCP should be able to produce a concise action brief that translates diagnostics into
+  practical workflow recommendations, including existing tools and custom helper ideas.
+
+## PR Chunk 1: Dogfood Hypothesis Harness
+
+Add a repeatable local experiment harness that runs the old and new hypothesis battery and
+emits compact local artifacts.
+
+Proposed command:
+
+```bash
+codex-usage-tracker dogfood-agentic
+```
+
+Initial behavior:
+
+- Refresh active usage by default, with `--include-archived` opt-in.
+- Run `usage_test_hypotheses` over the old hypothesis set:
+  - token waste in large low-output calls
+  - cache/cold-resume pressure
+  - repeated file rediscovery
+  - shell churn
+  - model/effort choice
+  - weekly allowance change
+- Run the new follow-up hypothesis set:
+  - large low-output calls as cleanup target
+  - repeated file rediscovery concentrated in safe file identities
+  - shell churn as repeated probing
+  - context pressure driving expensive calls
+  - local content-index/thread-trace follow-up needed for intent
+  - allowance-change claims not ready without weekly spans
+- Run direct evidence tools:
+  - `usage_large_low_output_calls`
+  - `usage_shell_churn`
+  - `usage_repeated_file_rediscovery`
+  - `usage_allowance_diagnostics`
+  - `usage_suggest_investigations`
+  - `usage_investigate` for `token_waste` and `workflow_churn`
+- Write a compact JSON summary and optional Markdown brief.
+
+Acceptance criteria:
+
+- Harness output declares scope: refresh status, archived setting, privacy mode, evidence
+  limit, and artifact paths.
+- Harness asserts privacy invariants: no indexed content, no raw fragments, no raw command
+  output, and no full paths in compact outputs.
+- Harness records expected family routing for the old and new hypotheses.
+- Harness can be run locally without publishing or contacting external services.
+- Add focused tests for summary shape and privacy flags using synthetic data.
+
+## PR Chunk 2: Skill And Plugin Guidance Refresh
+
+Update bundled skills and docs so Codex agents use the improved investigation flow.
+
+Guidance changes:
+
+- Lead broad usage questions with `usage_suggest_investigations`.
+- Use `usage_test_hypotheses` when the user frames the request as:
+  - "I'd like to be able to..."
+  - "I will accomplish this using..."
+  - "I'm missing access to..."
+  - "my hypothesis was true/false..."
+- Use direct tools after the hypothesis result:
+  - `usage_large_low_output_calls` for large low-output/context pressure.
+  - `usage_repeated_file_rediscovery` for repeated safe file identities.
+  - `usage_shell_churn` for command churn.
+  - `usage_allowance_diagnostics` and `usage_allowance_export` for limit-change claims.
+- Explain `unclassified_shell_script` plainly:
+  - It is a mixed or legacy bucket where the tracker cannot safely recover one specific
+    command root from aggregate indexed data.
+  - It is still evidence of churn, but needs thread trace or future indexed command detail
+    before prescribing a specific command-level fix.
+- Recommend existing tools and possible custom solutions when diagnosing waste:
+  - Headroom or similar context-pressure tools when available.
+  - Project notes, handoff templates, helper scripts, test selectors, file summaries, or
+    targeted commands when repeated rediscovery or shell churn appears.
+
+Acceptance criteria:
+
+- Bundled plugin skill files and source skill files stay in sync.
+- MCP docs describe the recommended investigation sequence.
+- Tests or docs snapshots prove the guidance mentions hypothesis testing, direct evidence
+  follow-up, `unclassified_shell_script`, and existing/custom remediation options.
+
+## PR Chunk 3: Actionable Recommendation Brief
+
+Add a user-facing aggregate report/MCP tool that converts diagnostics into a compact
+remediation brief.
+
+Proposed tool:
+
+```text
+usage_action_brief(...)
+```
+
+Initial inputs:
+
+- `goal`: optional, default `token_waste`
+- `since`, `until`, `thread`
+- `include_archived`
+- `evidence_limit`
+- `privacy_mode`
+
+Output shape:
+
+- `schema`
+- `content_mode`
+- `includes_indexed_content`
+- `includes_raw_fragments`
+- `privacy_mode`
+- `filters`
+- `summary`
+- `actions[]`
+  - `finding`
+  - `confidence`
+  - `evidence`
+  - `likely_waste_pattern`
+  - `recommended_workflow_change`
+  - `recommended_existing_tool`
+  - `recommended_custom_solution`
+  - `how_to_verify`
+  - `recommended_next_tools`
+- `caveats`
+
+Initial action families:
+
+- Large low-output/context pressure:
+  - recommend shorter handoffs, fresh thread with summary, context-pressure tooling, and
+    direct verification with `usage_large_low_output_calls` and `usage_call_detail`.
+- Repeated file rediscovery:
+  - recommend durable file summaries, project notes, helper commands, and narrower reads.
+- Shell churn:
+  - recommend stopping repeated retry loops, summarizing failures, using test selectors or
+    helper scripts, and inspecting thread traces.
+- Allowance-change readiness:
+  - recommend weekly diagnostics/export only when evidence is ready; otherwise explain why
+    public claims are premature.
+
+Acceptance criteria:
+
+- New schema is documented in CLI JSON schema docs and MCP docs.
+- MCP tool and CLI JSON path return the same payload builder.
+- Payload remains aggregate/shareable by default.
+- Tests cover at least one action from each initial action family using synthetic fixtures.
+- Dogfood harness can optionally include the action brief.
+
+## Phase Exit Criteria
+
+This phase is complete when:
+
+- The dogfood harness can be run before future MCP changes.
+- The bundled skill/plugin teaches agents the intended investigation flow.
+- The action brief can turn evidence into concrete user-facing remediation steps.
+- Full local validation passes.
+- No dashboard UI work has been started as part of this phase.
+
+## Release Guidance
+
+- If the phase only lands the harness and docs, ship as a patch.
+- If `usage_action_brief` becomes a new public MCP/API surface, ship as the next minor
+  release, likely `0.17.0`.

codex_usage_tracking-0.17.0/docs/agentic-investigation-hardening-roadmap.md

@@ -0,0 +1,159 @@
+# Agentic Investigation Hardening Roadmap
+
+This roadmap follows the exploratory MCP experiments run on 2026-07-08. The goal is to make Codex Usage Tracker useful as an agent-facing investigation partner, not just a dashboard data source.
+
+Product stance stays unchanged:
+
+- Local-first and unofficial.
+- Aggregate/shareable evidence first.
+- Explicit local content-index tools only when the user asks for deeper local diagnosis.
+- No raw context by default.
+- Recommendations must name evidence, missing evidence, confidence, and next verification step.
+
+## Experiment Findings
+
+The agentic layer already identifies meaningful waste patterns:
+
+- Large low-output calls are real and actionable.
+- High context pressure dominates recent usage.
+- Repeated file rediscovery is measurable and severe.
+- Shell churn exists, but command labels are too cloudy.
+- Allowance-change evidence is currently insufficient, which is the correct conservative result.
+
+The rough edges are agent-facing rather than purely analytical:
+
+- `usage_suggest_investigations(goal=...)` returns too few ideas for broad discovery.
+- `usage_investigate(...)` returns large nested payloads that are hard for agents to consume.
+- There is no first-class hypothesis-testing endpoint matching the preferred user framing.
+- Shell churn command labels collapse too often into `unknown_command`.
+- Local evidence export can report confusing aggregate fields for some branches.
+- Some filters and archived-row behavior need targeted regression tests.
+
+## Target Interaction Shape
+
+When a user asks for exploratory analysis, the agent should answer in this shape:
+
+```text
+I'd like to be able to ...
+I will accomplish this using ...
+I'm missing access to ...
+My hypothesis was true/false/partially true because ...
+Next action ...
+```
+
+The MCP should make that easy by returning this structure directly, with compact evidence and explicit caveats.
+
+## PR Chunk 1: Suggestions And Compact Investigation Payloads
+
+Improve existing entry points before adding new tools.
+
+Changes:
+
+- Expand `usage_suggest_investigations(...)` so broad goals can return multiple useful suggestions instead of one sparse row.
+- Add a compact mode or bounded evidence shape for `usage_investigate(...)` that avoids dumping full dashboard rows unless explicitly requested.
+- Preserve current schema compatibility by adding fields rather than removing stable fields.
+- Add tests proving broad suggestions include token waste, cache failure, workflow churn, allowance change, and overview.
+- Add tests proving compact investigation payloads include enough fields for actionability: finding, evidence summary, confidence, missing access, next tools.
+
+Acceptance criteria:
+
+- A user asking "what should I investigate?" receives a menu, not a single option.
+- A user asking "look through usage for token waste" receives concise findings that an agent can summarize without parsing massive nested rows.
+- Existing MCP contract tests remain green.
+
+## PR Chunk 2: Hypothesis Runner MCP/API Surface
+
+Add a first-class hypothesis-testing tool.
+
+Proposed tool:
+
+- `usage_test_hypotheses(...)`
+
+Initial inputs:
+
+- `question`
+- optional `hypotheses`
+- `since`, `until`, `thread`, `include_archived`
+- `evidence_limit`
+- `privacy_mode`
+
+Output shape:
+
+- `schema`
+- `content_mode`
+- `includes_indexed_content`
+- `includes_raw_fragments`
+- `question`
+- `hypotheses[]`
+  - `id`
+  - `hypothesis`
+  - `status`: `true`, `false`, `partially_true`, `insufficient_evidence`
+  - `confidence`
+  - `i_would_like_to_be_able_to`
+  - `i_will_accomplish_this_using`
+  - `i_am_missing_access_to`
+  - `evidence_summary`
+  - `counter_evidence`
+  - `next_action`
+  - `recommended_next_tools`
+
+Initial built-in hypothesis families:
+
+- token waste
+- cache/cold-resume failure
+- repeated file rediscovery
+- shell churn
+- effort/model choice
+- allowance change
+
+Acceptance criteria:
+
+- The tool can evaluate supplied hypotheses and default hypotheses.
+- It returns explicit true/false/partial/insufficient decisions.
+- It does not require raw context.
+- It recommends lower-level MCP tools when evidence is insufficient.
+
+## PR Chunk 3: Evidence Quality Hardening
+
+Fix the diagnostic surfaces that made recommendations cloudy.
+
+Changes:
+
+- Improve shell command normalization so common command families do not collapse into `unknown_command`.
+- Add tests for repeated `sed`, `rg`, `git`, `nl`, `npm`, `python`, `pytest`, and package-manager commands.
+- Tighten `usage_local_evidence_export(...)` aggregate summaries so `occurrences`, `call_count`, and `total_tokens` are meaningful for every branch.
+- Add regression tests for `include_archived=false` across the new agentic, low-output, shell, file, export, and hypothesis surfaces.
+- Make repeated file rediscovery recommendations more specific when safe fields are available: basename, extension, operation mix, adjacent retouch count, and trace handles.
+
+Acceptance criteria:
+
+- Shell churn reports are readable without raw command output.
+- Shareable local evidence export does not show confusing zero counts for supported branches.
+- Active-only filters do not surface archived rows in evidence samples.
+
+## Later Dashboard Work
+
+Do not start with UI. Once the APIs are stable:
+
+- Add a Diagnostics Notebook module for hypothesis testing.
+- Show "hypothesis true/false/partial" cards.
+- Link each card to Calls, Threads, Call Investigator, and local evidence export.
+
+## Validation Plan
+
+Each implementation PR should run:
+
+```bash
+.venv/bin/python -m ruff check .
+PYTHONPATH=src .venv/bin/python -m mypy
+PYTHONPATH=src .venv/bin/python -m pytest tests/cli/test_mcp_integration.py tests/cli/test_cli_release.py
+.venv/bin/python scripts/check_release.py
+git diff --check
+```
+
+Broader tests should be run when touching parser/indexing logic:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m pytest
+PYTHONPATH=src .venv/bin/python -m compileall src
+```

codex_usage_tracking-0.17.0/docs/agentic-mcp-skill-roadmap.md

@@ -0,0 +1,105 @@
+# Agentic MCP And Skill Roadmap
+
+Codex Usage Tracker has moved from static usage summaries toward local investigation tools that can help an AI analyst find waste, explain allowance evidence, and suggest concrete fixes. The next step is to make that experience intentional: agents should start from user goals, choose the right tracker endpoints, and return clear evidence-backed recommendations instead of making users pick from a long MCP tool catalog.
+
+## Product Stance
+
+- Local-first and unofficial remain non-negotiable.
+- Aggregate reports stay the default for normal usage answers.
+- Content-index tools remain explicit local investigation tools and must label when indexed snippets or local fragments can appear.
+- Remediation should be first-class: every investigation should make it clear what to do next and how to verify whether the change helped.
+- The MCP should help the model drive the tracker, but it should not claim access to OpenAI's internal ledger or account-wide usage outside local Codex logs.
+
+## Target Experience
+
+Users should be able to ask questions like:
+
+- "Look through my usage for token waste."
+- "Did my weekly allowance change?"
+- "Why is my 5-hour counter weird?"
+- "What should I fix first?"
+- "Where am I rediscovering the same files?"
+- "Which calls are big but low value?"
+
+The agent should then:
+
+1. Refresh or check local index freshness.
+2. Pick an investigation plan.
+3. Use stable MCP/API reports.
+4. Return findings with confidence and caveats.
+5. Recommend concrete workflow/tooling changes.
+6. Offer a verification path using dashboard rows, call investigator links, or follow-up MCP reports.
+
+## Payload Shape
+
+New agent-facing report payloads should converge on:
+
+- `goal`: the user intent or investigation kind.
+- `summary`: top finding, evidence count, confidence, privacy mode, data scope.
+- `findings`: normalized rows with `finding`, `evidence`, `confidence`, `why_it_matters`, `recommended_action`, `verify_with`, and `privacy_notes`.
+- `recommended_next_tools`: MCP calls the agent can use when the answer needs more detail.
+- `caveats`: limits such as stale index, missing pricing, missing allowance observations, archived sessions excluded, or outside usage possible.
+
+## Logical Units
+
+### Unit 1: Roadmap And Direction
+
+- Add this roadmap.
+- Keep existing behavior unchanged.
+- Use it as the reference for the next code PRs.
+
+### Unit 2: Agentic Investigation Orchestrator
+
+Add new MCP/API reports:
+
+- `usage_suggest_investigations(...)`
+  - Returns suggested investigations based on available local data and optional user goal.
+  - Does not require raw context.
+  - Suggestions should include which tool to call, why it matters, default parameters, and privacy caveats.
+
+- `usage_investigate(...)`
+  - Takes a goal such as `token_waste`, `allowance_change`, `cache_failure`, `workflow_churn`, or `overview`.
+  - Chains existing report builders instead of duplicating analysis logic.
+  - Returns a compact evidence-backed answer payload using the target shape above.
+
+Initial goals:
+
+- `token_waste`: combine large low-output calls, shell churn, repeated file rediscovery, report pack, and high-token calls.
+- `allowance_change`: route to weekly allowance diagnostics and strict export when sharing is likely.
+- `cache_failure`: use high-token calls, cache ratio, context-window percent, and large low-output evidence.
+- `workflow_churn`: use shell churn and repeated file rediscovery.
+- `overview`: use status, summaries, recommendations, and report pack evidence.
+
+### Unit 3: Skill Makeover
+
+Rewrite `codex-usage-api` around user intents:
+
+- Start with a small "intent router" instead of a long tool list.
+- Prefer `usage_investigate(...)` for broad goals.
+- Prefer `usage_suggest_investigations(...)` when the user asks for ideas.
+- Keep explicit privacy boundaries for raw context and content search.
+- Teach remediation structure: `Evidence`, `Likely waste pattern`, `Next action`, `How to verify`.
+- Mention Headroom and custom local automation only as conditional recommendations when evidence supports them.
+
+### Unit 4: Documentation And Examples
+
+- Update MCP docs to present agentic entrypoints first.
+- Keep the full tool catalog, but make it secondary.
+- Add one or two concise example prompts and response-shape notes.
+- Update JSON schema docs for new payload contracts.
+
+### Unit 5: Release Readiness
+
+- Add contract tests for the two new payloads.
+- Add MCP release-list tests for the new tools.
+- Run focused tests, full Python test suite, release checker, and package build before release.
+- Ship as the next minor release after the already-published `0.16.0`, likely `0.16.1` if treated as follow-up MCP polish or `0.17.0` if positioned as the agentic MCP release.
+
+## Non-Goals For This Pass
+
+- No new database schema.
+- No raw prompt/tool-output export.
+- No hosted data collection.
+- No dashboard redesign.
+- No replacement for existing specific diagnostic tools.
+- No claim that allowance diagnostics can read OpenAI's internal ledger.