claude-prospector 0.7.0__tar.gz

claude_prospector-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Beaulieu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_prospector-0.7.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: claude-prospector
+Version: 0.7.0
+Summary: Claude Code token usage analyzer with optimization recommendations. Surfaces what's eating your budget across the 5h / 7d / Sonnet-7d billing windows, with per-model and nested per-agent attribution and skill adoption tracking. Ships both an interactive dashboard and a conversational analysis skill.
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: ruff~=0.6.0; extra == "dev"
+Requires-Dist: pytest~=8.0; extra == "dev"
+Dynamic: license-file

claude_prospector-0.7.0/README.md

@@ -0,0 +1,335 @@
+# claude-prospector
+
+Token usage analyzer for Claude Code that surfaces where your budget is going across all three billing windows, with per-model and per-agent attribution and concrete optimization recommendations.
+
+## Why
+
+Claude Code tracks three billing buckets (5h rolling, 7d rolling, Sonnet-only 7d) but provides no per-agent or per-skill visibility. This tool reads Claude Code's local JSONL session files and generates a dashboard that breaks down where your tokens are going.
+
+## Install as a Claude Code plugin
+
+The easiest way to use `claude-prospector` is as a Claude Code plugin — no manual
+cloning or path configuration required.
+
+```bash
+claude plugin marketplace add glitchwerks/plugins
+claude plugin install claude-prospector@glitchwerks
+```
+
+### Prerequisite: Python package
+
+The plugin invokes `python -m claude_prospector` under the hood, so the Python
+package must be importable in the environment Claude Code uses. Install with either:
+
+- **From a local clone**: `uv pip install -e .`
+- **Directly from GitHub**: `uv pip install "git+https://github.com/glitchwerks/claude-prospector.git"`
+
+> A future enhancement (#67) tracks eliminating this two-step install so `claude plugin update` is sufficient on its own.
+
+## First-run setup
+
+After installing claude-prospector for the first time (or after a plugin
+update), open a new Claude Code session. You'll see a banner:
+
+> claude-prospector requires setup. Run /setup-prospector to materialise
+> the Python venv.
+
+Run `/setup-prospector` once. The skill will:
+
+1. Discover a Python 3.10+ interpreter on your system.
+2. Create a plugin-owned venv at `${CLAUDE_PLUGIN_DATA}/venv/`.
+3. Install `claude-prospector` from PyPI into that venv.
+4. Verify the install and record a setup-state flag.
+
+After setup completes, open a new session — the banner will be gone and
+the dashboard, skill-tracking, and usage-analysis features will work
+normally.
+
+You'll need to re-run `/setup-prospector` only when:
+
+- The plugin updates to a new version (banner: "venv is for vX but
+  plugin is vY").
+- The venv is corrupted or deleted (banner: "venv at <path> is
+  unreachable or corrupt").
+- You move to a new machine (per-machine setup; flag is not portable
+  across machines).
+
+**Note:** The plugin's hook scripts still run under the harness-provided
+`python` and require a working harness-environment Python interpreter.
+The venv created by `/setup-prospector` is used by the hooks for
+subprocess spawning only.
+
+### Migration from v0.6.0
+
+After upgrading to v0.7.0, open a new Claude Code session. A banner will
+prompt you to run `/setup-prospector`. This is a one-time action per
+machine.
+
+If you previously installed `claude-prospector` into `~/.claude/.venv`,
+you can leave that install in place — Pattern W hooks always use the
+plugin-owned venv via an absolute path. To reclaim disk you may
+`uv pip uninstall claude-prospector` from `~/.claude/.venv` after setup;
+this is optional.
+
+## What the plugin provides
+
+v0.4.0 ships the full plugin surface:
+
+- **Interactive dashboard** — HTML report with three-bucket budget gauges (5h / 7d / Sonnet-7d), per-model donut and bar charts, per-agent token attribution with nested sub-agent tracing, skill-invocation counts, and per-project breakdowns.
+- **`usage-analysis` skill** — conversational analysis with recommendations. Answers questions like "am I close to my Sonnet limit?", "where are my tokens going?", and "which agent uses the most?". Triggered by natural-language phrases.
+- **`usage-dashboard` skill** — bare regeneration surface. Triggered by phrases like "regenerate the dashboard" or "rebuild my usage dashboard"; writes the HTML file and reports the path, without interpreting the data.
+- **`skill-tracker` hook** (PreToolUse, always-on) — logs `Skill` tool-use events to the state directory for the `by_skill` and skill-passed-vs-invoked analyses.
+- **`dashboard-regen` hook** (Stop, opt-in) — auto-regenerates the dashboard after every session when the `autoregen` user-config is enabled via the plugin manager (`/plugin reconfigure claude-prospector` or at install time).
+
+### Configuration (autoregen)
+
+The `dashboard-regen` Stop hook is opt-in. Toggle it through the Claude Code
+plugin manager — no manual file edits required:
+
+```
+/plugin reconfigure claude-prospector
+```
+
+You will be prompted to enable or disable `autoregen`. You can also set it at
+install time when the plugin manager shows the initial configuration prompt.
+
+To inspect the current plugin state, use the read-only CLI:
+
+```bash
+python -m claude_prospector config --show
+```
+
+This prints the legacy `config.json` contents if present. The authoritative
+value is the `autoregen` setting shown in the plugin manager.
+
+> **Upgrading from v0.4.x?** If you previously ran
+> `python -m claude_prospector config --enable-autoregen`, your old
+> `config.json` is still readable via `--show`. The hook will log a one-time
+> advisory message to `hook.log` the first time it runs with the new
+> user-config path. Re-toggle via `/plugin reconfigure claude-prospector` to
+> move to the managed setting. The old `config.json` file is not deleted.
+
+### State storage
+
+When running as a plugin, state (dashboard HTML, hook log, skill-tracking JSONL files) is stored under the `${CLAUDE_PLUGIN_DATA}` directory — the Anthropic-documented persistent state location that survives plugin updates.
+
+Users upgrading from v0.4.0 get a **one-time automatic migration**: on the first session after upgrade, any existing files from `~/.claude/claude-prospector/` are moved into `${CLAUDE_PLUGIN_DATA}` and the legacy directory is removed.
+
+For testing or non-plugin use, set `CLAUDE_PROSPECTOR_BASE_DIR` to override the location entirely (takes priority over `${CLAUDE_PLUGIN_DATA}`).
+
+## Development / Standalone CLI
+
+For working on the package directly, or running it without the Claude Code plugin.
+
+### Install for development
+
+```bash
+git clone https://github.com/cbeaulieu-gt/claude-prospector.git
+cd claude-prospector
+uv pip install -e ".[dev]"   # installs runtime + ruff + pytest
+```
+
+Requires Python 3.10+.
+
+### Run the CLI directly
+
+```bash
+# Default: last 7 days, opens in browser
+python -m claude_prospector
+
+# Rolling window matching billing buckets
+python -m claude_prospector --window 5h
+python -m claude_prospector --window 7d
+
+# Custom date range
+python -m claude_prospector --from 2026-04-01 --to 2026-04-09
+
+# Output to file instead of opening browser
+python -m claude_prospector --output report.html --no-open
+
+# Custom Claude data directory
+python -m claude_prospector --data-dir "D:\other\.claude"
+
+# Set budget limits for gauge percentages
+python -m claude_prospector --limit-5h 600000 --limit-7d 4000000 --limit-sonnet-7d 2000000
+```
+
+### Subcommands
+
+All functionality is accessed through named subcommands. Bare `claude-prospector` prints help and exits 0.
+
+#### `dashboard` — interactive HTML dashboard
+
+```bash
+# Default: last 7 days, opens in browser
+claude-prospector dashboard
+
+# Rolling window matching Claude billing buckets
+claude-prospector dashboard --window 5h
+claude-prospector dashboard --window 7d
+
+# Custom date range
+claude-prospector dashboard --from 2026-04-01 --to 2026-04-09
+
+# Output to file instead of opening browser
+claude-prospector dashboard --output report.html --no-open
+
+# Custom Claude data directory
+claude-prospector dashboard --data-dir "D:\other\.claude"
+
+# Set budget limits for gauge percentages
+claude-prospector dashboard --limit-5h 600000 --limit-7d 4000000 \
+    --limit-sonnet-7d 2000000
+
+# Emit JSON (for scripting / CI)
+claude-prospector dashboard --format json
+```
+
+All flags are unchanged from the pre-refactor form — only their location
+moved (now under the `dashboard` subparser).
+
+#### `session-summary` — deterministic session recap (new in v0.2.0)
+
+Reads a single Claude Code transcript JSONL file and emits a structured
+JSON summary suitable for consumption by the `/whats-next` skill or any
+other tool that needs to know what a session did.
+
+```bash
+claude-prospector session-summary --path ~/.claude/projects/<hash>/<session>.jsonl
+```
+
+**Flags:**
+
+| Flag | Default | Description |
+|---|---|---|
+| `--path PATH` | *(required)* | Path to the transcript JSONL file |
+| `--format {json,text}` | `json` | Output format. `json` is the machine-readable contract; `text` is a human-readable debug view |
+| `--max-actions N` | `50` | Cap on emitted actions. `0` disables the cap |
+
+**Sample output (`--format json`):**
+
+```json
+{
+  "project": "claude-prospector",
+  "intent": "Implement the session-summary subcommand for the /whats-next skill",
+  "actions": [
+    "Edited claude_prospector/cli/session_summary.py",
+    "Created tests/test_session_summary.py",
+    "Ran pytest tests/test_session_summary.py -x",
+    "Dispatched code-reviewer sub-agent"
+  ],
+  "stoppedNaturally": true
+}
+```
+
+**Exit codes:**
+
+| Code | Meaning | stderr |
+|---|---|---|
+| `0` | Success — JSON written to stdout | *(silent)* |
+| `1` | IO failure reading `--path` (file missing, permission denied, etc.) | `session-summary: cannot read transcript at '<path>': <OSError class>: <message>` |
+| `2` | File readable but contains no external user turns (empty session, zero-byte file, whitespace-only file) | `session-summary: transcript '<path>' contains no user turns` |
+| `3` | File has content but none of it parses as JSONL | `session-summary: transcript '<path>' is not valid JSONL` |
+
+On any non-zero exit, stdout is empty and stderr contains exactly one line.
+
+#### Migration note
+
+The old flag-only form **no longer works** after v0.2.0:
+
+```bash
+# REMOVED — will print help and exit 0, not run the dashboard
+claude-prospector --format json
+
+# CORRECT — migrate all callers to:
+claude-prospector dashboard --format json
+```
+
+Any script, skill, or CI step that invokes `claude-prospector` with bare flags
+(no subcommand) must be updated to use `claude-prospector dashboard [flags]`.
+
+### Testing
+
+```bash
+pytest                # ~151 tests, typically finishes in under 5 seconds
+```
+
+### Linting & formatting
+
+```bash
+ruff check .          # lint
+ruff format .         # autoformat in-place
+ruff format --check . # format gate (used in CI — exits non-zero on drift)
+```
+
+### CI
+
+GitHub Actions runs on every PR and push to `main`:
+
+- **lint** (Ubuntu): `ruff check .` + `ruff format --check .`
+- **test** (Ubuntu + Windows, Python 3.10): `pytest`
+
+Both jobs must be green before a PR can merge.
+
+## Nested agent attribution
+
+When Claude Code sessions dispatch sub-agents that themselves dispatch further
+sub-agents, `claude-prospector` traces the full depth and attributes tokens to the
+complete root-to-leaf chain rather than just the immediate leaf.
+
+- **Data model.** Each `MessageRecord` carries an `agent_path: tuple[str, ...]`
+  field (e.g. `("general-purpose", "project-planner", "Explore")`) and a
+  parallel `agent_type: str` stored field. Both are populated together at parse
+  time; the parser enforces the invariant `agent_type == agent_path[-1]` (when
+  `agent_path` is non-empty). `agent_type` is not a computed property — it is a
+  plain dataclass field, so consumers that construct `MessageRecord` with an
+  explicit `agent_type=` argument continue to work without change. The two
+  fields are kept in sync by the parser, not by the dataclass itself.
+
+- **`by_agent` keys.** The aggregator's `by_agent` dict is keyed by the full
+  path joined with U+2192 (`→`), for example
+  `"general-purpose→project-planner→Explore"`. Depth-1 sessions produce
+  single-segment keys identical to the pre-change shape, so existing
+  integrations are unaffected.
+
+- **Per-session `agents` list.** Each session's `agents` list contains only
+  the deepest-leaf path per chain (e.g. a depth-3 chain
+  `general-purpose → project-planner → Explore` contributes one entry,
+  `"general-purpose→project-planner→Explore"`). Sibling chains that share a
+  leaf name but differ in their ancestor are both kept — neither is a prefix
+  of the other. This rule preserves the dashboard JS's per-agent token
+  apportionment, which divides session totals by `s.agents.length`.
+
+- **Depth limit.** Path tuples may contain up to **10 segments** total —
+  the root agent plus up to 9 levels of nested sub-agents
+  (`_MAX_AGENT_PATH_LENGTH = 10`). Beyond that, the parser emits a single
+  `UserWarning` and stops descending; deeper messages are bucketed under the
+  last walked ancestor. The warning fires at most once per session parse (not
+  once per overflowing message), as do the cycle and OSError warnings below.
+  On Windows, junction-based cycles are caught by this same cap rather than
+  by the POSIX visited-set short-circuit.
+
+- **Sanitization.** A literal `→` appearing inside an agent name is replaced
+  with `﹖` (U+FE56) at parse time and a `UserWarning` fires. The sanitized
+  name is used throughout (parse, aggregation, dashboard key) so attribution
+  data is preserved even when the invariant is violated.
+
+- **Deferred.** Dashboard tree visualization (sunburst, indented tree,
+  expand/collapse) is out of scope for this release. The existing flat agent
+  list in the dashboard JS receives path-keyed entries but no hierarchical
+  rendering yet.
+
+## Dashboard
+
+The generated HTML dashboard includes:
+
+- **Budget gauges** - estimated usage against each billing bucket (5h, 7d, Sonnet-only 7d)
+- **Model breakdown** - donut chart and daily stacked bar chart (Opus/Sonnet/Haiku)
+- **Agent breakdown** - token usage per agent with model attribution
+- **Skill usage** - invocation counts per skill
+- **Project breakdown** - tokens per project
+- **Session drill-down** - click a day to see individual sessions with agents, tokens, and model split
+
+## How It Works
+
+Reads JSONL session files from `~/.claude/projects/`. Each session file contains timestamped assistant messages with model name and token usage. Subagent metadata (`.meta.json`) maps child agent tokens to their agent type. Skill invocations are extracted from `Skill` tool-use entries.

claude_prospector-0.7.0/claude_prospector/__init__.py

@@ -0,0 +1,10 @@
+"""Claude Prospector — Claude Code usage analytics dashboard."""
+
+from __future__ import annotations
+
+try:
+    import importlib.metadata as _meta
+
+    __version__: str = _meta.version("claude-prospector")
+except Exception:
+    __version__ = "0.0.0+local"

claude_prospector-0.7.0/claude_prospector/__main__.py

@@ -0,0 +1,53 @@
+"""CLI entry point for claude-prospector — subparser dispatcher."""
+
+from __future__ import annotations
+
+import sys
+
+import claude_prospector
+from claude_prospector.cli import config, dashboard, session_summary
+
+
+def main() -> None:
+    """Parse top-level subcommand and dispatch to the appropriate runner."""
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        prog="claude-prospector",
+        description=(
+            "Claude Code token usage tools. "
+            "Run 'claude-prospector <subcommand> --help' for details."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"claude-prospector {claude_prospector.__version__}",
+    )
+    subparsers = parser.add_subparsers(
+        dest="subcommand",
+        metavar="subcommand",
+    )
+
+    dashboard.build_parser(subparsers)
+    session_summary.build_parser(subparsers)
+    config.build_parser(subparsers)
+
+    args = parser.parse_args()
+
+    if args.subcommand is None:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.subcommand == "dashboard":
+        sys.exit(dashboard.run(args))
+
+    if args.subcommand == "session-summary":
+        sys.exit(session_summary.run(args))
+
+    if args.subcommand == "config":
+        sys.exit(config.run(args))
+
+
+if __name__ == "__main__":
+    main()