claude-code-plugins

Pre-computed context

Current branch: !git branch --show-current 2>/dev/null || echo "unknown"
Repo slug: !git rev-parse --show-toplevel 2>/dev/null | sed 's|.*/||' || echo "unknown"
ccusage availability: !command -v npx >/dev/null 2>&1 && echo "npx present" || echo "npx MISSING"
Hook event log: !bash "${CLAUDE_PLUGIN_ROOT}/skills/observability/scripts/probe-observability-state.sh" --hook-events 2>/dev/null || echo "unknown"
OTEL collector :4318: !bash -c 'source "${CLAUDE_PLUGIN_ROOT}/skills/observability/otel/net-probe.sh" && port_status 4318' 2>/dev/null || echo unknown
OTEL store: !bash "${CLAUDE_PLUGIN_ROOT}/skills/observability/scripts/probe-observability-state.sh" --otel-store 2>/dev/null || echo "unknown"

Purpose

Single place to read Claude Code observability — where to read telemetry, how the
collector/dashboard/store fit together, and cross-session trend reports. CC shorthand =
Claude Code CLI — see context/operator-setup.md "Naming".
Progressive disclosure lives in context/ (read on demand — do not recap inline).

Read-only — never writes user-visible state except a report file under
${CLAUDE_PLUGIN_DATA}/reports/ (when --write is passed). Honors
context/privacy.md.

Not /claude-ops:known-issues — that skill tracks Anthropic product bugs and GitHub issues.
This skill reads your captured telemetry and ops signals.

Context ladder (read on demand)

OTEL query and retention helpers live in otel/ (private backends) with stable entry points in
scripts/. Machine provisioning owns the Collector configuration and all long-running service
and dashboard lifecycle.

Arguments

$ARGUMENTS — scope filter OR action. First token chooses behavior:

Reporting scopes (default behavior)

Optional second token: --write (persist report to
${CLAUDE_PLUGIN_DATA}/reports/claude-observability-<date>.md instead of stdout).

When the scope is week or larger, optionally offer a self-contained HTML dashboard rendering
the same multi-metric trend report alongside the markdown (session/day stay markdown; markdown
remains the durable record).

Maintenance actions

Action invocation: /claude-ops:observability clean [flags].

clean requires explicit user confirmation before running when invoked by the model — show
--dry-run output first unless user already passed --dry-run or explicitly ordered cleanup.

Ad-hoc telemetry reads (no special action)

When the user asks to inspect traces, logs, metrics, or hook data outside a scope report:

1. Read context/read-routing.md — pick source
2. Read context/otel-queries.md or context/data-sources.md — run queries
3. Apply context/privacy.md — redact before responding

Workflow — scope reports

0. Dispatch — action vs scope

If $1 == "clean": shift, delegate to scripts/clean.sh "$@" and return its exit code.

if [[ "${1:-}" == "clean" ]]; then
  shift
  exec bash "${CLAUDE_PLUGIN_ROOT}/skills/observability/scripts/clean.sh" "$@"
fi
SCOPE="${1:-week}"
case "$SCOPE" in
  session|day|week|month|all) ;;
  since:*) ;;
  *) echo "Unknown scope: $SCOPE. Use session|day|week|month|since:YYYY-MM-DD|all|clean" >&2; exit 1 ;;
esac

1. Gather data sources

Read context/data-sources.md. Summary:

2–5. Compute, privacy, render, output

Unchanged — context/data-sources.md, context/privacy.md,
context/output-format.md.

Cross-references

• /claude-ops:known-issues — CC product bugs (not telemetry reads)

Gotchas

• Empty stores are normal on first run — degrade gracefully
• session_id drift — use cwd + branch + time proximity
• Stop hook unreliability — do not rely on Stop for aggregation
• cc_spans / cc_traces — views skip bind until cc-traces.json has content

What this skill does NOT do

• Does not track GitHub bugs — use /claude-ops:known-issues
• Does not modify code — read-only
• Does not replace built-in /insights or your own retrospective workflow
• Does not write to memory unless user explicitly saves