gitcrawl mirrors GitHub issues and pull requests into local SQLite for maintainers and agents. It provides local search, related-thread clustering, JSON output, and a terminal interface without running a local HTTP service.

Homebrew is the smallest install on macOS and Linux:

brew install openclaw/tap/gitcrawl

Prebuilt archives for macOS, Linux, and Windows are available from GitHub Releases. The installation guide also covers source builds and update checks; source builds require Go 1.26.5 or newer. A Docker source build keeps its runtime state under one mounted directory.

Sync needs a GitHub token from GITHUB_TOKEN or gh auth token. Generating summaries and embeddings also needs OPENAI_API_KEY; semantic search and clustering use those stored embeddings, while ordinary sync and keyword search do not.

Initialize the local archive, sync a repository, and query it:

gitcrawl init
gitcrawl sync openclaw/gitcrawl
gitcrawl search issues "SQLite" -R openclaw/gitcrawl \
  --state open --json number,title,url --limit 5

The default sync fetches open issues and pull requests and sweeps recently closed threads. Use --state all for an initial historical backfill, --include-comments for discussion, or --with pr-details for pull request files, commits, checks, and review state.

The quickstart continues through embeddings, clusters, and the terminal UI. For a quota-conscious maintainer workflow, see Maintainer archive workflow.

Direct search supports keyword, semantic, and hybrid modes over one local repository. The gh search-shaped form used above lets existing scripts query the SQLite mirror without spending GitHub search quota. Add --sync-if-stale 5m when an agent should refresh an old mirror before searching.

Commands support structured output with --json. Gitcrawl reserves stdout for results and sends diagnostics to stderr, so its output can feed jq or another process directly. See Search and Automation for the supported shapes.

gitcrawl refresh owner/repo runs sync, embedding, and clustering in order. Clusters combine vector similarity with direct GitHub references, then preserve maintainer decisions such as local closes, member exclusions, and canonical threads across later runs.

Open gitcrawl tui [owner/repo] for the keyboard- and mouse-driven cluster browser. The TUI reads SQLite and refreshes its view every 15 seconds; it does not call GitHub itself. See Clustering, Governance, and TUI.

The default local archive keeps configuration, SQLite data, vectors, caches, and logs in platform-native user directories. Exact paths and environment overrides are in Configuration.

Portable stores publish a compact SQLite snapshot through Git so multiple machines can share a read-mostly archive. Cloud archives configure authenticated reads and snapshot publication through a separately deployed Worker service. Local, portable, and cloud modes keep distinct storage and credential boundaries.

Octopool owns pooled live gh reads. Gitcrawl keeps local mirror, search, clustering, and TUI workflows; use gh or Octopool for final live verification and GitHub write actions. See the migration note.

The command reference lists the complete CLI surface and flags.

make build
make test
make check

make check runs the formatting, vet, vulnerability, dead-code, coverage, smoke, release-script, and snapshot gates used by CI.

MIT — see LICENSE.