Quickstart

Five minutes from clean machine to a populated cluster view.

#1. Install and initialize

# Build (or download a release archive — see Installation).
git clone https://github.com/openclaw/gitcrawl.git
cd gitcrawl
mkdir -p "$HOME/bin"
go build -o "$HOME/bin/gitcrawl" ./cmd/gitcrawl

# Create config + database under ~/.config/gitcrawl.
gitcrawl init

Defaults written:

~/.config/gitcrawl/config.toml
~/.config/gitcrawl/gitcrawl.db
~/.config/gitcrawl/cache/
~/.config/gitcrawl/vectors/
~/.config/gitcrawl/logs/

#2. Set credentials

export GITHUB_TOKEN="<github-token>"                 # required for sync
export OPENAI_API_KEY="<openai-api-key>"             # required for embeddings

Either set them in your shell profile or store them in ~/.config/gitcrawl/config.toml:

[env]
GITHUB_TOKEN = "<github-token>"
OPENAI_API_KEY = "<openai-api-key>"

gitcrawl doctor confirms the credentials are visible and reports their source.

#3. Sync a repository

gitcrawl sync openclaw/gitcrawl

By default this fetches open issues and pull requests, plus a sweep of recently closed rows so the local store does not rot. Add --include-comments for review threads, --include-pr-details (or --with pr-details) for PR files, commits, checks, and workflow runs.

Need exact rows? Use --numbers:

gitcrawl sync openclaw/gitcrawl --numbers 123,456 --include-comments

#4. Embed and cluster

The refresh command runs sync → embed → cluster end to end:

gitcrawl refresh openclaw/gitcrawl

You can run the stages individually if you want finer control — see Refresh and embed and Clustering.

#5. Browse clusters

Open the TUI:

gitcrawl tui openclaw/gitcrawl
# or just `gitcrawl tui` and the most recently synced repo is inferred

↑/↓ navigate clusters, Enter opens member detail
a opens the action menu, # jumps to a number, n loads neighbors, p switches repo
Right-click and mouse wheel work in most terminals

For a non-interactive view:

gitcrawl clusters openclaw/gitcrawl --sort size --min-size 5
gitcrawl cluster-detail openclaw/gitcrawl --id 12
gitcrawl neighbors openclaw/gitcrawl --number 123 --limit 10

#6. Search the local cache

gitcrawl search openclaw/gitcrawl --query "download stalls" --mode hybrid

The same command also accepts the gh search shape, which makes it a drop-in for scripts that already speak gh:

gitcrawl search issues "manifest cache" \
  -R openclaw/gitcrawl \
  --state open \
  --json number,title,state,url,updatedAt,labels \
  --limit 30

Add --sync-if-stale 5m to refresh the local mirror first when it is older than the duration you tolerate.

#7. Wire up the `gh` shim (optional)

mkdir -p "$HOME/bin"
ln -sf "$(command -v gitcrawl)" "$HOME/bin/gitcrawl-gh"
gitcrawl-gh search issues "download stalls" -R openclaw/gitcrawl --json number,title,url
gitcrawl-gh pr view 123 -R openclaw/gitcrawl --json number,title,state,url
gitcrawl-gh xcache stats

Most read-only gh calls answer locally, mutating commands pass straight through to the real gh. See gh shim for the full surface.

#Where to next

Concepts — what threads, durable clusters, and embeddings actually mean
Sync — every flag for hydrating the local store
Clustering — tuning the cluster graph for a specific repo
Automation — JSON contracts for agents and scripts