Stargraph

Evidence-first analytics over your GitHub stars: every capability claim is backed by a source URL, an evidence-record hash, and a confidence score, so an agent can verify a signal instead of trusting it. There is no LLM in the scoring path: a weighted composite you can read in one file (src/scoring.ts) computes the rankings, and the same functions back both a CLI and an MCP stdio server.

Stargraph syncs starred repositories into a local SQLite ledger, extracts evidence-backed capabilities from metadata, docs, and manifests, computes similarity lenses, and answers questions about the resulting graph.

V1 intentionally avoids cloning repositories by default. GitHub is the source of truth, SQLite is canonical local state, and graph/cluster/search outputs are rebuildable projections.

Quick Start

Requirements: Node >= 22.5 (uses the built-in node:sqlite module), zero runtime dependencies.

npm install
npm run build
# --limit caps how many stars are fetched; --deep-limit caps how many get the
# full metadata/docs/manifest pass (default 25). Set both to deep-analyze all 50.
GITHUB_TOKEN="$GITHUB_TOKEN" node dist/src/cli.js sync --limit 50 --deep-limit 50 --json
node dist/src/cli.js search "local-first agent memory tools" --json
node dist/src/cli.js similar owner/repo --json
node dist/src/cli.js explain owner/repo --json
node dist/src/cli.js serve

By default data is stored under ~/.stargraph. Use --data-dir ./data or --db ./data/stargraph.sqlite for a project-local ledger.

Commands

• sync: fetch starred repos and, for the first --deep-limit of them (default 25), their metadata, docs/manifests, releases, issues, PRs, topics, and languages, plus optional local star-list imports. --limit caps how many starred repos are fetched; raise --deep-limit to deep-analyze more of them.

• search "<use case>": rank repos by useful + robust fit.

• similar owner/repo: compare repos across functional, architecture, dependency, maintenance, portability, risk, and docs-language lenses.

• explain owner/repo: show capabilities, dependencies, health, risk, and evidence.

• clusters: group repos into high-signal functional/tooling clusters.

• query "<question>": a keyword query router that dispatches to search, similar, explain, or clusters based on keywords and an owner/repo pattern in the question (it does not parse natural language).

• build-graph: write a Kuzu-compatible CSV/Cypher projection.

• serve: expose MCP tools over stdio.

Star Lists

GitHub's documented REST starring API exposes starred repositories and starred_at. V1 stores lists as first-class data, but imports them from a local JSON file until GitHub exposes a stable public lists endpoint.

{
  "lists": [
    {
      "name": "agent memory",
      "description": "Repos related to local-first memory",
      "repos": ["owner/name", "other/repo"]
    }
  ]
}

Import during sync with:

node dist/src/cli.js sync --lists-file ./lists.json --json

Authentication

The GitHub token is read only from the GITHUB_TOKEN or GH_TOKEN environment variable, or from an explicit --token flag. Nothing is written back to disk.

Design

• GitHub is the source of truth. Stargraph never mutates upstream state; it only reads.

• SQLite is canonical local state. The ledger is the single place durable data lives.

• Graph, cluster, and search outputs are rebuildable projections derived from the ledger, so they can be regenerated at any time.

• Raw API snapshots are retained for auditability, which lets a capability claim be traced back to the exact response it came from.

• Scoring is code, not an LLM. Similarity and ranking are a weighted composite computed by the functions in src/scoring.ts, and the CLI and MCP server call the same code. Given a fixed ledger snapshot and a fixed clock the output is deterministic; the personal-relevance score includes a recency term derived from starred_at versus the current time, so that component moves as time passes, and result envelopes are stamped with a last_analyzed_at timestamp.

Limitations

• macOS and Linux are the tested platforms; Windows is untested.

• Requires Node >= 22.5 because it depends on the built-in node:sqlite module, which is not available on older Node versions.

• GitHub does not expose a stable public endpoint for star lists, so lists are imported from a local JSON file rather than synced automatically.

• V1 does not clone repositories, so analysis is limited to metadata, docs, manifests, and other data reachable through the GitHub REST API.

License

MIT. See LICENSE.