claude-prospector

claude-prospector

Claude Code efficiency and hygiene toolkit. Surfaces token spend across the three billing windows with per-model / per-agent / per-skill attribution, and audits your effective Claude Code configuration for agent and skill overlap.

Why

claude-prospector bundles a set of skills that target distinct angles of "is my Claude Code setup healthy?":

Skill	Angle
usage-analysis	where your tokens are going
usage-dashboard	regenerate the cost dashboard surface
claude-audit	where your config has agent / skill overlap or bloat
session-analysis	whether a session stayed on task (opt-in LLM judgment)

Claude Code's built-in /usage shows current-session token totals and — for Max/Pro subscribers — plan-usage bars on the same screen. It doesn't surface multi-day history, per-agent attribution with sub-agent nesting, per-skill invocation counts, or per-project breakdowns, and there's no way to ask "where are my Sonnet-7d tokens going this week?" from inside the session. There's also no built-in way to detect when two installed plugins ship overlapping code-reviewer agents or near-duplicate skills.

claude-prospector reads Claude Code's local JSONL session files to break tokens down by model, agent (with sub-agent nesting), skill, and project across all three billing windows (5h rolling, 7d rolling, Sonnet-only 7d), and inventories your custom + plugin-provided agents and skills to produce a structured overlap / conflict report with keep / modify / drop recommendations.

Install

1. Add the marketplace and install the plugin

claude plugin marketplace add glitchwerks/plugins
claude plugin install claude-prospector@glitchwerks

2. First-run setup

After installing (or after a plugin update), open a new Claude Code session. You will see a banner:

claude-prospector requires setup. Run /setup-prospector to materialise the Python venv. After setup completes, open a new session to activate the dashboard, skill-tracking, and usage-analysis features.

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 all features will work normally.

You will 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 (setup is per-machine; the flag is not portable).

What you can do

usage-analysis skill

Conversational analysis with recommendations. Triggered by natural-language phrases such as:

• "am I close to my Sonnet limit?"
• "where are my tokens going?"
• "which agent uses the most tokens?"
• "give me a usage analysis"

The skill reads your session data and responds inline — no browser required.

usage-dashboard skill

Bare dashboard regeneration. Triggered by phrases like "regenerate the dashboard" or "rebuild my usage dashboard". Writes the HTML file and reports the path, without interpreting the data.

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 and nested sub-agent tracing
• 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

claude-audit skill

Audits your project's effective Claude Code configuration — custom and plugin-provided agents and skills together — and produces a structured overlap / conflict report with keep / modify / drop recommendations scoped to the project's stated objectives. Triggered by /claude-prospector:claude-audit or natural-language phrases such as:

• "audit my claude config"
• "find overlap in my agents"
• "check for skill conflicts"
• "are any of my agents duplicates"
• "what's redundant in my setup"

The skill is read-only — it does not modify any files. All recommendations are presented for your review.

session-analysis skill

The interpretive (LLM) complement to the deterministic session-audit CLI. Where session-audit extracts ask-vs-done for free, session-analysis adds the judgment layer: did the agent stay on the original ask, and what did it acknowledge skipping?

The skill loads session-audit's extract (the 1a fields), then has the agent produce two judgment fields — Variance and What was NOT done — and persists a combined record via the variance-save subcommand.

Key constraints: