From plugin-introspector
White-box monitoring and self-improvement meta-plugin for Claude Code workflow plugins. Monitors tool usage, token consumption, API calls, and execution patterns. Analyzes collected data to generate data-driven improvement proposals. Activated by keywords: "introspector", "monitor", "analyze plugin", "token usage", "dashboard", "evaluate", "optimize", "improve plugin", "security", "compliance".
How this skill is triggered — by the user, by Claude, or both
Slash command
/plugin-introspector:plugin-introspectorThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> A meta-plugin that monitors Claude Code workflow plugin execution at white-box level,
agents/anomaly-detector.mdagents/api-tracker.mdagents/auto-optimizer.mdagents/context-auditor.mdagents/improvement-generator.mdagents/plugin-profiler.mdagents/quality-evaluator.mdagents/quick-scanner.mdagents/security-auditor.mdagents/security-reporter.mdagents/token-optimizer.mdagents/workflow-analyzer.mdresources/ci-cd-integration.mdresources/data-schema.mdresources/docker-compose.otel.ymlresources/improvement-apply-protocol.mdresources/improvement-pipeline.mdresources/orchestration-protocol.mdresources/otel-collector-config.yamlresources/otel-collector-guide.mdA meta-plugin that monitors Claude Code workflow plugin execution at white-box level, collects execution data, and generates data-driven improvement proposals.
A monitoring and analysis meta-plugin that provides end-to-end visibility into Claude Code workflow plugin execution. Collects tool traces, API interactions, token usage, and execution patterns via hooks. Provides analysis agents that identify bottlenecks, evaluate quality, detect anomalies, and generate concrete improvement proposals.
.claude-plugin/plugin.json and skills/)SKILL.md).md file in agents/)improveBefore any command, resolve the session directory:
1. Run: ls -t ~/.claude/plugin-introspector/sessions/ | head -1
→ Gives the most recent session ID
2. If --session {id} was provided: use that ID instead
3. Set: SESSION_DIR = ~/.claude/plugin-introspector/sessions/{resolved-id}
4. Verify: stats.json exists in SESSION_DIR
5. If not found: display "No session data. Run a session with hooks enabled first."
Full details: resources/orchestration-protocol.md
When --target {plugin-name} is specified:
1. Search for plugin at: {working_dir}/plugins/{plugin-name}/
2. Fallback: check marketplace.json for source path
3. Catalog plugin components → store in SESSION_DIR/target_plugin.json
4. If not found: display "Plugin '{name}' not found" with available list
When --target is omitted:
input_summary fields for plugin-specific paths~/.claude/plugin-introspector/
├── sessions/{session-id}/
│ ├── meta.json # Session metadata (git info, collection_tier)
│ ├── tool_traces.jsonl # Pre/post tool traces with input_summary
│ ├── api_traces.jsonl # API request/response metrics
│ ├── otel_traces.jsonl # OTel spans (hook-generated or merged native)
│ ├── stats.json # Aggregated session statistics
│ ├── evaluation.json # Quality evaluation results (from evaluate)
│ ├── security_events.jsonl # DLP violations, command risk events (from security hooks)
│ └── target_plugin.json # Discovered target plugin info (from --target)
├── session_history.jsonl # Cross-session summary records
├── evaluation_history.jsonl # Cross-session evaluation scores
├── alerts.jsonl # Anomaly detection alerts
├── improvement_log.jsonl # Applied improvement history
├── aggregates.json # Pre-computed cross-session aggregates (from Stop hook)
├── security_baseline.json # Security baseline for anomaly comparison (optional)
├── telemetry.jsonl # Opt-in anonymous telemetry (PI_TELEMETRY=1)
├── plugin-profiles/{plugin}/ # Per-plugin workflow profiles and baselines
├── otel-export/ # Tier 1: OTel Collector File Exporter output
└── otel-collector/ # Tier 1: Collector binary and config
| Command | Agent | Options |
|---|---|---|
status | — | --session {id} |
dashboard | — | --session {id}, --full |
flow | — | --session {id} |
profile | plugin-profiler | --target {plugin} (required) |
analyze | workflow-analyzer | --session {id}, --target {plugin} |
tokens | token-optimizer | --session {id} |
api | api-tracker | --session {id} |
context | context-auditor | --session {id}, --target {plugin} |
evaluate | quality-evaluator | --session {id}, --target {plugin} |
alerts | anomaly-detector | --session {id} |
optimize * | auto-optimizer | --target {plugin}, --component {file} |
improve | improvement-generator | --session {id}, --target {plugin} (required) |
report | 5 agents (see below) | --session {id}, --target {plugin} |
apply | — | (reads proposals from last improve/optimize) |
trace | — | --tool {name}, --errors, --slow, --last {N} |
web | — | --otel, --json, --csv |
quick-scan | quick-scanner | --target {plugin} (required) |
security-scan | — | --target {plugin} (required) |
security-audit | security-auditor | --session {id} |
security-dashboard | — | --session {id} |
compliance-report * | security-reporter | --period {30d|7d|date~date} |
rotate-data | — | --dry-run, env: PI_RETENTION_DAYS, PI_RETENTION_LINES |
otel-setup * | — | install, start, stop, status, env |
otel-security-map * | — | --watch, --stats |
* available, experimental
Details: resources/orchestration-protocol.md
All analysis agents are invoked via the Task tool using the prompt template defined in orchestration-protocol.md:
1. Read the agent definition: agents/{agent-name}.md
2. Read the relevant JSONL data files from SESSION_DIR (apply truncation per Data Size Management)
3. Construct prompt from Task Prompt Template (see orchestration-protocol.md)
4. Invoke Task with subagent_type: "general-purpose", model per agent's Model Assignment
5. Parse agent's JSON output
6. Display results / write to SESSION_DIR
For multi-agent commands (report, improve, optimize):
1. Read all data files once and reuse across agents
2. For 'report': run independent agents in parallel (workflow-analyzer, token-optimizer, api-tracker, context-auditor), then quality-evaluator
3. For 'improve': run analysis agents + load cross-session data (evaluation_history, improvement_log, plugin profile), aggregate all, pass to improvement-generator with improvement-pipeline.md procedure
4. For 'optimize': read evaluation.json + evaluation_history + improvement_log + target component, pass to auto-optimizer
status — Current Session Overviewstats.jsondashboard — htop-style Real-time DashboardBash: scripts/dashboard.sh {session-id} [--full]flow — Execution Flow Tree (OTel)otel_traces.jsonlparent_span_idprofile — Generate Plugin Profile--target)target_plugin.json)~/.claude/plugin-introspector/plugin-profiles/{plugin}/profile.jsonphase-baselines.json and learned-patterns.jsonl if not presentanalyze — Deep Workflow Analysistool_traces.jsonl + otel_traces.jsonltokens / api / context — Single-Agent Analysis CommandsAll follow the same pattern: resolve session → read data → invoke agent → display output.
| Command | Agent | Data Files | Extra |
|---|---|---|---|
tokens | token-optimizer (sonnet) | tool_traces.jsonl + api_traces.jsonl + stats.json | — |
api | api-tracker (sonnet) | api_traces.jsonl | — |
context | context-auditor (sonnet) | api_traces.jsonl + tool_traces.jsonl | --target: read SKILL.md + agents for static cost |
evaluate — Quality Evaluation (LLM-as-Judge)--target scopes evaluation)tool_traces.jsonl + otel_traces.jsonl + stats.jsonSESSION_DIR/evaluation.json~/.claude/plugin-introspector/evaluation_history.jsonl:
weighted_score, scoreskey_metrics (tool_calls, total_tokens_est, errors, error_rate, duration_ms)phase_breakdown (optional, only for phased workflows)improvement_signals: top_waste_sources (top 3 waste entries)improvements_active (IDs where status == "applied")workflow.type == "phased"):
plugin-profiles/{plugin}/phase-baselines.jsonsessions_count, set maturity.baselines_available = true if count ≥ 5~/.claude/plugin-introspector/improvement_log.jsonl
status == "applied" and post_score == null--target specified: only check entries matching target_pluginweighted_score with pre_scorepost_score and set status to validated or regressedalerts — Anomaly Detection~/.claude/plugin-introspector/alerts.jsonl → display recent alertstool_traces.jsonl + session_history.jsonl + alerts.jsonloptimize — Auto-Optimize (APE Loop) (available, experimental)--target)--component or auto-select lowest-scoring)evaluation.json (run evaluate first if missing)evaluation_history.jsonl + improvement_log.jsonl (for contrastive analysis + historical learning)CAUTION: Review all diffs before applying. See resources/improvement-apply-protocol.md.
improve — Generate Improvement Proposals--target)evaluation_history.jsonl (last 20 records)improvement_log.jsonl (all for target plugin)profile.json, phase-baselines.json, learned-patterns.jsonlreport — Full Analysis Reportapply — Apply Improvement Proposalsimprove or optimize output (proposals)improvement_log.jsonlevaluate --target {plugin} after next session to validate improvements"CAUTION: Never auto-apply. Each proposal requires explicit user approval.
quick-scan — Quick Plugin Diagnosis (1-minute)--target)security-scan.sh for security scoreUse case: First-time plugin evaluation, PR review, quick health check
Details: agents/quick-scanner.md
rotate-data — Data Retention ManagementBash: scripts/rotate-data.shPI_RETENTION_DAYS (default: 30)PI_RETENTION_LINES (default: 1000)Environment variables:
PI_RETENTION_DAYS=30: Days to keep session directoriesPI_RETENTION_LINES=1000: Lines to keep in JSONL filesPI_DRY_RUN=1: Preview what would be deleted without actually deletingPI_AUTO_ROTATE=1: Auto-run at session end (optional)Example:
# Dry run to see what would be deleted
PI_DRY_RUN=1 /plugin-introspector rotate-data
# Keep only 7 days of data
PI_RETENTION_DAYS=7 /plugin-introspector rotate-data
security-scan — Plugin Static Security Analysis--target)Bash: scripts/security-scan.sh {plugin-path}alerts.jsonl if any foundEnvironment variables:
PI_ENABLE_SECURITY=1: Enables runtime command risk loggingPI_ENABLE_DLP=1: Enables DLP scanningPI_SECURITY_BLOCK=1: Enables CRITICAL command blocking (use with caution)Note:
security-check.shintentionally omits|| truein plugin.json so thatexit 2can block CRITICAL commands whenPI_SECURITY_BLOCK=1. All other hook scripts use|| trueper meta-rules.
Details: resources/security-patterns.md
security-audit — Session Security Audittool_traces.jsonl + otel_traces.jsonl + stats.json + security_events.jsonl + alerts.jsonlsecurity-dashboard — Security Risk VisualizationBash: scripts/security-dashboard.sh {session-id}compliance-report — Compliance Report Generation (available, experimental)session_history.jsonl for specified periodalerts.jsonl + security_events.jsonl + improvement_log.jsonl (aggregated)security-scan for each active pluginotel-setup — OTel Collector Setup (Tier 1) (available, experimental)Bash: scripts/setup-otel-collector.sh {subcommand}
install: Download OTel Collector Contrib binary (~100MB+)start: Start collector with otel-config.yaml (OTLP receiver → file exporter)stop: Stop collectorstatus: Show collector status, export data info, environment variablesenv: Print shell environment variables to setAfter setup, the collection tier automatically upgrades from Tier 0 to Tier 1. Hook scripts detect the running collector and skip redundant OTel span generation. Native OTel spans (with accurate token counts) are merged at session end.
otel-security-map — OTel Security Event Mapper (available, experimental)Bash: scripts/otel-security-mapper.sh [session-id|--watch|--stats]<session-id>: Process specific session's OTel data--watch: Real-time mapping mode--stats: Show security statistics from OTel dataUse case: Enhanced security analysis with native OTel data (Tier 1+)
trace — Raw Trace Viewertool_traces.jsonl with filters: --tool {name}, --errors, --slow, --last {N}web — Export for External Tools--otel, --json, --csvAll environment variables are opt-in. Default behavior requires no configuration.
| Variable | Default | Description |
|---|---|---|
PI_ENABLE_SECURITY | 0 | Enable runtime command risk logging |
PI_ENABLE_DLP | 0 | Enable DLP (sensitive data detection) |
PI_SECURITY_BLOCK | 0 | Block CRITICAL commands (use with caution) |
PI_RETENTION_DAYS | 30 | Days to keep session data |
PI_RETENTION_LINES | 1000 | Lines to keep in JSONL files |
PI_DRY_RUN | 0 | Preview data rotation without deleting |
PI_AUTO_ROTATE | 0 | Auto-rotate data at session end |
PI_SHOW_REMINDER | 1 | Show PI commands reminder at session start |
PI_TELEMETRY | 0 | Enable opt-in anonymous telemetry (local only) |
PI_BASELINE_MAX_AGE | 30 | Days of history for security baseline |
Telemetry Policy (PI_TELEMETRY):
telemetry.jsonl — never transmitted externallyscripts/telemetry.sh status to view collected data| Document | Purpose |
|---|---|
| orchestration-protocol.md | Agent invocation, data passing, pipeline composition |
| improvement-apply-protocol.md | Safe improvement application with rollback |
| improvement-pipeline.md | Quantified improvement generation procedure |
| data-schema.md | JSONL record format specifications |
| security-patterns.md | Security threat patterns, DLP signatures, compliance mapping |
| ci-cd-integration.md | GitHub Actions, GitLab CI, Jenkins pipeline examples |
| skill-activation-guide.md | Optional Forced Eval Hook installation for 84% skill activation |
| otel-collector-guide.md | OTel Collector setup with ClickStack/HyperDX |
| docker-compose.otel.yml | Docker Compose for OTel stacks |
| otel-collector-config.yaml | Standalone OTel Collector configuration |
| Agent | Purpose | Model |
|---|---|---|
| workflow-analyzer | Execution pattern analysis, bottleneck detection | sonnet |
| token-optimizer | Token waste identification, optimization suggestions | sonnet |
| context-auditor | Context window usage audit | sonnet |
| api-tracker | API interaction monitoring and analysis | sonnet |
| quality-evaluator | LLM-as-Judge multi-dimension evaluation | sonnet |
| anomaly-detector | Real-time anomaly detection via Z-score/MA | haiku |
| plugin-profiler | Target plugin workflow profiling | haiku |
| improvement-generator | Concrete improvement proposal generation | opus |
| auto-optimizer | APE-based automatic prompt optimization | opus |
| security-auditor | Session security audit and risk classification | haiku |
| security-reporter | Compliance report generation (SOC 2, ISO 27001) | sonnet |
| quick-scanner | Fast plugin structure and security diagnosis | haiku |
| Skill | Purpose |
|---|---|
| meta-rules | Agent/skill writing rules and anti-bloat constraints |
| analysis-patterns | Reusable analysis patterns and heuristics |
| cost-tracking | Model-specific pricing and cost calculation |
The full improvement cycle connects improve, evaluate, and the apply protocol:
┌─────────┐ ┌───────────┐ ┌─────────┐ ┌──────────┐
│ improve │────▶│ user │────▶│ apply │────▶│ log to │
│ (propose)│ │ review │ │ (backup, │ │ improve- │
│ │ │ (approve?)│ │ edit, │ │ ment_log │
│ │ │ │ │ verify) │ │ .jsonl │
└─────────┘ └───────────┘ └─────────┘ └────┬─────┘
│
▼
┌─────────┐ ┌───────────┐ ┌─────────────────────────┐
│ rollback │◀───│ regressed │◀───│ evaluate (next session) │
│ (if bad) │ │ score? │ │ → checks pending │
│ │ │ │ │ post_scores in log │
└─────────┘ └───────────┘ └─────────────────────────┘
improve generates proposals with diffs and meta-rules validationimprovement_log.jsonl with post_score: nullevaluate run (step 9 — Closed Loop Check) detects pending entries and fills post_scorepost_score >= pre_score): mark status: "validated"post_score < pre_score - 0.5): suggest rollback, mark status: "regressed"When evaluate detects regression:
1. Display: "Improvement {proposal_id} caused score regression: {pre_score} → {post_score}"
2. Offer rollback: "Restore from backup? (yes/no)"
3. If yes: follow rollback procedure in improvement-apply-protocol.md
4. Log rollback to improvement_log.jsonl
CLAUDE_TOOL_NAME + structured Skill name via jq — skip if Skill invocation targets plugin-introspectorimprove --target plugin-introspector: extra caution, meta-rules strictly enforcednpx claudepluginhub hungrytech/hungrytech-claude-skills --plugin plugin-introspectorAudits Claude Code configurations for best practices in skills, instructions, MCP servers, hooks, plugins, security, over-engineering, and context efficiency via file scans and focused checks. Invoke with /claudit [focus-area].
Analyzes Claude Code agent extensions and generates self-contained interactive HTML wiki reports with security audits, architecture diagrams, and plugin profiles. Activates on analysis requests, GitHub plugin URLs, or local paths.
Analyzes Claude Code session health using PRISM: token usage, CLAUDE.md audits, session failures, and project listings.