Setup Prospector

Setup claude-prospector

This skill materialises the plugin-owned Python venv that the plugin's hooks need to run claude-prospector as a subprocess. Run it once after first install and after any plugin version update.

Step 1: Resolve ${CLAUDE_PLUGIN_DATA}

Read the CLAUDE_PLUGIN_DATA environment variable, but do not trust it blindly. When this skill is driven from a main session, CLAUDE_PLUGIN_DATA may be set to a different plugin's data dir (observed in the wild as .../data/codex-openai-codex). Before using it, confirm its basename begins with claude-prospector- — i.e. it is this plugin's data dir. The marketplace suffix may legitimately differ (-glitchwerks for the public install, or another suffix for a local/forked marketplace), so match the claude-prospector- prefix, not a hardcoded marketplace. If CLAUDE_PLUGIN_DATA is unset, empty, or its basename belongs to a different plugin, ignore it and compute the default instead (using the canonical glitchwerks marketplace slug):

~/.claude/plugins/data/claude-prospector-glitchwerks/

The slug is - — claude-prospector published from the glitchwerks marketplace — with every character outside [a-zA-Z0-9_-] replaced by a hyphen.

Create the directory if it does not exist.

Step 2: Discover Python

Find a Python ≥ 3.10 interpreter using this probe chain (stop at first success):

1. flag.interpreter from the prior setup-state.json (if a flag exists from a

previous run, try that interpreter first).

1. $CLAUDE_PROSPECTOR_BOOTSTRAP_PYTHON environment variable (absolute path).
2. py -3 (Windows only).
3. python3
4. python

Probe each candidate with:

 -c "import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)"

If all candidates fail, ask the user: > "No Python ≥ 3.10 interpreter found. Please provide an absolute path to > a Python 3.10+ executable, or set CLAUDEPROSPECTORBOOTSTRAP_PYTHON."

Step 3: Wipe the existing venv

If ${CLAUDE_PLUGIN_DATA}/venv/ exists, remove it entirely:

shutil.rmtree(/venv)

This is always-wipe-first (spec D4). A partial venv from a failed previous run is handled correctly by this unconditional removal.

Step 4: Create the venv

 -m venv /venv

Where `` is the interpreter found in Step 2. If this fails, surface the stderr to the user and do NOT proceed to Step 5.

Step 5: Install claude-prospector from PyPI

First, ensure pip is available in the new venv:

 -m ensurepip --upgrade

Then install:

 -m pip install claude-prospector==

Where ` is the current plugin version (read from pyproject.toml [project].version, falling back to .claude-plugin/plugin.json version`).

If $CLAUDE_PROSPECTOR_PIP_SPEC is set, use its value as the entire package spec instead of claude-prospector== (test/dev override only).

If pip fails, surface the stderr verbatim, wipe the partial venv, and do NOT proceed to Step 6.

Step 6: Verify import

 -c "import claude_prospector"

If this fails, wipe the venv and report the import error. Suggest pip cache purge and retry if the error looks like a wheel issue.

Step 7: Write the setup-state flag

Write ${CLAUDE_PLUGIN_DATA}/setup-state.json with this shape:

{
  "version": "",
  "venv_path": "",
  "interpreter": "",
  "installed_at": ""
}

The venv_path is the absolute path to the venv root (e.g. C:/Users/alice/.claude/plugins/data/claude-prospector-glitchwerks/venv). The interpreter is the raw command string from Step 2 (e.g. py -3 or python3), not an absolute path, so re-setup can reuse it.

Step 8: Tell the user

Report success: > "Setup complete. Open a new Claude Code session to activate claude-prospector. > The dashboard, skill-tracking, and usage-analysis features will work normally > after the next session starts."

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: glitchwerks
• Source: glitchwerks/claude-prospector
• License: MIT
• Homepage: https://pypi.org/project/claude-prospector/

Install and usage instructions live in the source repository linked above.