Gitcrawl

Gitcrawl

Use local archive data first for GitHub issue and pull request questions. Browse or hit live GitHub APIs only when the local archive is stale, missing the requested scope, or the user asks for current external context.

Sources

• Config: resolve with gitcrawl doctor --json; fresh macOS installs default to ~/Library/Application Support/gitcrawl/config.toml, while Linux honors ${XDG_CONFIG_HOME:-~/.config}/gitcrawl/config.toml
• DB: resolve with gitcrawl doctor --json; fresh macOS installs default to ~/Library/Application Support/gitcrawl/gitcrawl.db, while Linux honors ${XDG_DATA_HOME:-~/.local/share}/gitcrawl/gitcrawl.db; portable-store installs may point at a configured store database instead of the default local DB
• Cache: resolve with gitcrawl init --json for new installs or from cache_dir in config; fresh macOS installs default to ~/Library/Caches/gitcrawl, while Linux honors ${XDG_CACHE_HOME:-~/.cache}/gitcrawl
• Vectors: resolve with gitcrawl init --json for new installs or from vector_dir in config; fresh macOS installs default to ~/Library/Application Support/gitcrawl/vectors, while Linux honors ${XDG_DATA_HOME:-~/.local/share}/gitcrawl/vectors
• Legacy installs may still resolve config, database, cache, vectors, and logs under ~/.config/gitcrawl/; check the active config before assuming a migrated path.
• Repo: openclaw/gitcrawl; on ClawSweeper this is checked out at ~/clawsweeper-workspace/gitcrawl
• Preferred CLI: gitcrawl; fallback to go run ./cmd/gitcrawl from a verified repo checkout if the installed binary is stale

Freshness

For recent/current questions, check freshness before analysis:

gitcrawl doctor --json

Routine refresh:

gitcrawl doctor
gitcrawl refresh owner/repo

Targeted refresh:

gitcrawl sync owner/repo --numbers 123,456 --with pr-details

--with pr-details hydrates PR files, commits, checks, workflow runs, and review-thread resolution state in the local archive. Use it when the review needs those details; it does not populate Octopool's separate gh cache.

For agent-driven discovery, prefer bounded freshness:

gitcrawl search issues "query" -R owner/repo --state open --sync-if-stale 5m --json number,title,url

Query Workflow

1. Resolve scope: owner/repo, issue/PR number, cluster id, keyword, label, author, state, or date range.
2. Check freshness for recent/current requests.
3. Use CLI for normal reads; use read-only SQL for precise counts/rankings.
4. Report absolute date spans, repo names, issue/PR numbers, cluster ids, and known gaps.

Common commands:

gitcrawl search issues "query" -R owner/repo --state open --json number,title,url
gitcrawl clusters owner/repo --sort size --min-size 5
gitcrawl cluster-detail owner/repo --id <id>
gitcrawl threads owner/repo --numbers 123 --include-closed --json

For an exact PR, read the archive with threads first. --include-closed keeps closed or merged candidates in scope; archive state is not proof of current GitHub state. Then use bare PATH gh for fresh metadata when needed, including before final merge/comment decisions:

gh pr view 123 -R owner/repo --json number,title,state,url,isDraft,headRefName,headRefOid

Drill down into checks only when needed:

gh pr checks 123 -R owner/repo --json name,state,bucket,link

Keep the existing Octopool-backed gh shim and use narrow JSON field lists so supported reads share its cache. Native gh uses headRefName/headRefOid for PR refs and bucket/link for check classification and URLs, not the old Gitcrawl field names.