stargaze

Cache and search your GitHub stars from the terminal. Pure Rust. Single binary. No cloud.

A small Rust CLI that pulls your starred GitHub repos into a local embedded database, lets you keyword-search them (README text included), and exposes the same cache to AI agents as an MCP server. No daemon, no cloud, no C dependencies.

Why

The GitHub starred-repos list is a shoebox of bookmarks with no real retrieval. Once you've starred more than a few hundred repos, finding "that one Postgres CLI I saw last month" means scrolling. stargaze turns your stars into a queryable local corpus that survives across machines, runs offline, and plugs into Claude / Cursor / any MCP-speaking agent.

Install

From crates.io:

cargo install stargaze

From source:

git clone https://github.com/bkataru/stargaze
cd stargaze
cargo install --path .

Needs Rust 1.76+. Everything is pure Rust — no libsqlite3, no openssl, no C toolchain. The release binary is fully static (aside from libc).

Prebuilt binaries for Linux / macOS / Windows are attached to every tagged release.

Quick start

# one-time: give stargaze a token to talk to the GitHub API
export GH_TOKEN=$(gh auth token)

# pull down your stars
stargaze sync

# ...and their READMEs (slower, pulls 1 request per repo)
stargaze sync --with-readmes

# search across the cache — now includes README text
stargaze search postgres
stargaze search 'vector db' --lang rust --limit 10
stargaze search cli --topic hacktoberfest

# run as an MCP server so agents can query your stars
stargaze serve

Commands

Global flags:

• --db <path> — override the database file (default: $XDG_DATA_HOME/stargaze/stars.redb)
• --token <pat> — pass a GitHub PAT explicitly instead of reading the env var

Storage

One file. Default location:

• Linux: ~/.local/share/stargaze/stars.redb
• macOS: ~/Library/Application Support/com.bkataru.stargaze/stars.redb
• Windows: %APPDATA%\bkataru\stargaze\data\stars.redb

Backed by redb — a pure-Rust embedded key-value store with ACID transactions. Each starred repo is stored as a JSON blob keyed by owner/name; a separate meta table tracks last-sync timestamp and count. README text is included in the same record (truncated to 64 KiB to keep the file lean).

Three equivalent surfaces: CLI, MCP, HTTP API

Every read-only operation is reachable from all three surfaces. You pick the one that matches your client:

All three surfaces dispatch through the same RepoIndex + Database handles, so search results are identical across them. Mutating operations (sync, readmes) are intentionally CLI-only for now.

HTTP API

stargaze api --bind 127.0.0.1:7879 --threads 4
# optionally require a bearer token:
stargaze api --bind 0.0.0.0:7879 --api-key "$(openssl rand -hex 32)"

curl http://127.0.0.1:7879/api/v1/health
curl 'http://127.0.0.1:7879/api/v1/search?q=postgres&limit=5'
curl http://127.0.0.1:7879/api/v1/stars/rust-lang/rust

Backed by tiny_http (pure Rust, blocking, no tokio). Thread pool size configurable via --threads. CORS is enabled (Access-Control-Allow-Origin: *) so you can hit it from localhost web UIs.

MCP server mode

stargaze serve runs a Model Context Protocol stdio server that exposes the local cache as a structured tool set. Any MCP-compatible client (Claude Desktop, Cursor, custom agents) can query your starred repos as typed data.

Example Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "stargaze": {
      "command": "stargaze",
      "args": ["serve"]
    }
  }
}

Tools exposed:

The implementation is hand-rolled JSON-RPC 2.0 over stdio — no tokio, no external MCP library — so the binary stays single-static and cold-starts instantly.

Auth

stargaze sync needs a GitHub token (any classic PAT or fine-grained token with read access to public metadata will do). Resolution order:

1. --token <pat> flag
2. GH_TOKEN environment variable
3. GITHUB_TOKEN environment variable

The easiest bootstrap if you already use the gh CLI:

export GH_TOKEN=$(gh auth token)

stargaze never shells out — all HTTP traffic goes through ureq with rustls (pure-Rust TLS).

Scheduled sync

systemd timer (Linux)

~/.config/systemd/user/stargaze-sync.service:

[Unit]
Description=stargaze — refresh GitHub stars cache

[Service]
Type=oneshot
Environment="GH_TOKEN=%h/.config/stargaze/token"
ExecStart=%h/.cargo/bin/stargaze sync --with-readmes --prune

~/.config/systemd/user/stargaze-sync.timer:

[Unit]
Description=Weekly stargaze sync

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

Enable it once: systemctl --user enable --now stargaze-sync.timer.

launchd (macOS)

~/Library/LaunchAgents/com.bkataru.stargaze.plist:

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
  <dict>
    <key>Label</key>  <string>com.bkataru.stargaze</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/bin/stargaze</string>
      <string>sync</string>
      <string>--with-readmes</string>
      <string>--prune</string>
    </array>
    <key>StartInterval</key> <integer>604800</integer>
    <key>EnvironmentVariables</key>
    <dict><key>GH_TOKEN</key><string>ghp_…</string></dict>
  </dict>
</plist>

Load: launchctl load ~/Library/LaunchAgents/com.bkataru.stargaze.plist.

GitHub Actions (run in the cloud, commit the cache)

See .github/workflows/ci.yml for the reusable CI pattern. A weekly sync workflow that commits the cache back to a private repo is straightforward: cargo install stargaze && stargaze sync --with-readmes && git add stars.redb && git commit && git push.

Benchmarks

stargaze ships with a full criterion bench suite:

cargo bench                       # run all workloads
cargo bench index_build           # only the index-build path
cargo bench search_cold           # cold (non-cached) searches
cargo bench search_warm           # LRU-cache hit path

Workloads covered:

End-to-end wall-clock via hyperfine:

hyperfine --warmup 1 'stargaze search postgres'
hyperfine --warmup 1 'stargaze sync'

Tests

Around 108 tests across unit + integration + live tiers:

cargo test                        # hermetic suite (88 tests, no network)
cargo test -- --ignored           # + 6 live tests that hit the real GitHub API

Live tests are gated on GH_TOKEN / GITHUB_TOKEN being present; if missing they short-circuit with a skip message instead of failing. The CI pipeline runs them on every push to main using the repo's own workflow token.

Full breakdown:

Comparison: stargaze vs miantiao-me/github-stars

Both projects address the same frustration. They make very different architectural choices.

The short version: stargaze is local-first, CI-tested, and runs anywhere Rust compiles. miantiao-me/github-stars offloads everything interesting (storage, embeddings, hosting) to Cloudflare. Different axes, same goal.

Roadmap

• v0.1 (current): sync, parallel README fetch, search with LRU cache, MCP stdio server, HTTP JSON API server, 108 tests, criterion benches, GH Actions CI + release workflow.
• v0.2: stargaze diff --since DATE — delta of additions/removals (already schema-ready via starred_at).
• v0.3: fastembed-rs local embeddings + cosine-similarity semantic search (stargaze semantic <query>).
• v0.4: export formats (markdown, opml, csv), stargaze categorize heuristic grouping, stargaze open <name> launcher.

License

MIT. See LICENSE.