Analytics And Adoption

July 21, 2026 ยท View on GitHub

Use this guide to answer a few common maintainer questions:

  • How much interest is the repo getting?
  • Which package ecosystems are seeing usage?
  • Can we see which projects depend on the repo or packages?
  • Can we identify who accessed the repo?

Run Artifact Analytics

For completed autocontext runs with persisted context-selection artifacts, summarize candidate versus selected context, selected token estimates, duplicate-content rate, useful-artifact recall, and freshness by generation. The report also emits diagnostics for duplicate selected content, low useful-artifact recall, and selected-token bloat.

cd autocontext
uv run autoctx analytics context-selection --run-id <run_id>
uv run autoctx analytics context-selection --run-id <run_id> --json

The TypeScript CLI exposes the same persisted report shape for npm-backed operator workflows:

autoctx context-selection --run-id <run_id>
autoctx context-selection --run-id <run_id> --json

For completed runs with persisted RunTrace artifacts, emit trace-grounded findings from the same reporter used by run-end writeups. Trace ids are the filenames under knowledge/analytics/traces/ without the .json suffix (for example trace-run-123 from knowledge/analytics/traces/trace-run-123.json). If a run only has an events stream, rebuild traces first:

cd autocontext
uv run autoctx analytics rebuild-traces --run-id <run_id> --json
uv run autoctx analytics trace-findings --trace-id <trace_id>
uv run autoctx analytics trace-findings --trace-id <trace_id> --kind weakness
uv run autoctx analytics trace-findings --trace-id <trace_id> --json

Use --kind writeup (the default) for a full trace-grounded summary with findings, failure_motifs, recovery_paths, and summary. Use --kind weakness for a recommendation-focused report with weaknesses, failure_motifs, recovery_analysis, and recommendations. Under --json, missing traces return a parseable payload such as {"status":"failed","error":"...","trace_id":"..."} and exit non-zero.

TypeScript: autoctx trace-findings

The TypeScript package ships a parallel autoctx trace-findings command that operates on a PublicTrace JSON file (the data plane primitive that flows through autoctx production-traces) rather than on a stored RunTrace by id. Cross-runtime parity is at the output layer: both runtimes emit a TraceFindingReport matching the TraceFindingReportSchema Zod contract, even though the input artifacts differ.

The TS command surfaces an agent-behavior taxonomy detectable from the PublicTrace transcript + outcome (tool_call_failure, agent_refusal, low_outcome_score, dimension_inconsistency), complementing the harness-event-typed findings the Python command produces.

# From the npm package (no Python runtime required):
autoctx trace-findings --trace ./trace.json          # Markdown report
autoctx trace-findings --trace ./trace.json --json   # JSON report
autoctx trace-findings --help                        # Usage

--trace <path> is required and must point to a JSON file matching PublicTraceSchema. Loading by stored trace id (--trace-id <id> against the ProductionTrace store) is a follow-up slice.

Operator trace-gate review

Cockpit and the terminal UI consume the same trace-finding report and harness-change proposal contracts instead of a TUI-only shape. The read model is available at GET /api/cockpit/runs/:run_id/trace-gates in both runtimes and in the TUI via /findings <run-id> or /trace-gates <run-id>.

The view surfaces findings with trace-message evidence refs, recurring failure modes with occurrence counts, proposed harness/context changes with target surfaces, gate decisions (accepted, rejected, inconclusive) with reasons, evidence artifact refs, and graceful missing_report, incomplete_analysis, and no_findings states.

Repository Traffic

For GitHub-hosted repo traffic, use the repository Traffic view:

  • GitHub UI: Insights -> Traffic
  • Metrics available: views, unique visitors, clones, unique cloners, top referrers, and popular content
  • Retention: GitHub only keeps the most recent 14 days in the UI

CLI/API equivalents:

gh api repos/greyhaven-ai/autocontext/traffic/views
gh api repos/greyhaven-ai/autocontext/traffic/clones
gh api repos/greyhaven-ai/autocontext/traffic/popular/referrers
gh api repos/greyhaven-ai/autocontext/traffic/popular/paths

Use weekly snapshots if you want longer-running trendlines.

Package Adoption

npm

The npm package page is the easiest package-level signal:

PyPI

PyPI does not provide a simple project-specific downloads dashboard in its main UI.

Practical options:

PyPI's /stats/ API is global PyPI-wide data, not per-project package downloads.

Dependents And "Used By"

GitHub dependency graph is the best built-in signal for public dependents.

What it can show:

  • public repos that declare this repo or package as a dependency
  • package ecosystem relationships when manifests are recognized

Important limitations:

  • the "Used by" sidebar only appears in some cases
  • it depends on dependency graph support and recognized manifests
  • it is not a complete picture of all real-world usage

Can We See Who Accessed The Repo?

Usually, no.

For a public GitHub repository:

  • you can see aggregate repo traffic
  • you generally cannot see exactly who viewed or cloned the repo

For organizations:

  • org owners can review the organization audit log for actor and repository events
  • that is useful for member/admin activity, not for identifying anonymous public viewers

Practical Recommendations

  • Check GitHub Traffic weekly and record the numbers somewhere durable if you care about trends.
  • Watch npm for public package uptake.
  • Use PyPI BigQuery if Python download counts become important enough to track regularly.
  • Check GitHub dependency graph and dependents for public adopters.
  • Do not expect individual-level viewer identity for public repository traffic.

Useful References