Gitcrawl

https://gitcrawl.sh/
Admin
Gitcrawl is a local-first GitHub triage tool that mirrors issues and pull requests into SQLite for...
Tokens:39,172
Snippets:356
Trust Score:5.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Verify Installation

Source: https://gitcrawl.sh/installation

Initialize the configuration and run the doctor command to verify the setup.

```bash
gitcrawl init           # creates config and data under platform default paths
gitcrawl doctor         # confirms config, database, and credential discovery
gitcrawl doctor --json  # same, machine-readable
```

--------------------------------

### Initial repository setup

Source: https://gitcrawl.sh/sync

Perform a full sync and embedding for a repository for the first time.

```bash
gitcrawl sync owner/repo --state all --include-comments
gitcrawl embed owner/repo
gitcrawl cluster owner/repo
```

--------------------------------

### One-step repository setup

Source: https://gitcrawl.sh/sync

Perform a full sync, embedding, and clustering in a single command.

```bash
gitcrawl refresh owner/repo --include-comments
```

--------------------------------

### Install and initialize gitcrawl

Source: https://gitcrawl.sh/quickstart

Build the binary from source and initialize the configuration and database directories.

```bash
# 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 the platform default runtime paths.
gitcrawl init
```

--------------------------------

### octopool login command for first-time setup

Source: https://gitcrawl.sh/gh-shim

Run this command only when setting up a new Octopool installation. It is part of the first-time Octopool setup workflow.

```bash
octopool login
```

--------------------------------

### Install via Homebrew

Source: https://gitcrawl.sh/installation

Use Homebrew to install the gitcrawl binary.

```bash
brew install openclaw/tap/gitcrawl
```

--------------------------------

### Install from GitHub Release

Source: https://gitcrawl.sh/installation

Download and extract a specific version and platform archive from GitHub releases.

```bash
# Replace VERSION and PLATFORM with the values you want.
VERSION=v0.10.0
PLATFORM=darwin_arm64
mkdir -p "$HOME/bin"
curl -L "https://github.com/openclaw/gitcrawl/releases/download/${VERSION}/gitcrawl_${VERSION#v}_${PLATFORM}.tar.gz" \
  | tar -xz -C "$HOME/bin" gitcrawl

gitcrawl --version
```

--------------------------------

### Wire up the gh shim

Source: https://gitcrawl.sh/quickstart

Example of using the search command and Octopool for GitHub API interactions.

```bash
gitcrawl search issues "download stalls" -R openclaw/gitcrawl --json number,title,url
octopool login
octopool gh api repos/openclaw/gitcrawl/pulls/123
```

--------------------------------

### Example JSON output for embed command

Source: https://gitcrawl.sh/refresh-and-embed

Displays the structure of the JSON output, including metadata about the run, counts of processed items, and details on any batch failures.

```json
{
  "repository": "owner/repo",
  "model": "text-embedding-3-small",
  "basis": "title_original",
  "selected": 21,
  "embedded": 20,
  "skipped": 0,
  "failed": 1,
  "retries": 3,
  "status": "ok",
  "failures": [
    { "batch_start": 16, "batch_end": 17, "attempts": 3, "status": 429, "type": "rate_limit", "code": "rate_limit_exceeded", "message": "..." }
  ],
  "run_id": 43
}
```

--------------------------------

### JSON output format for overrides

Source: https://gitcrawl.sh/governance

Example of the JSON structure representing a local override state.

```json
{ "repository": "owner/repo", "number": 123, "reason": "duplicate handled", "closed": true }
```

--------------------------------

### GitHub Actions CI integration

Source: https://gitcrawl.sh/automation

Example workflow step to refresh and snapshot clusters, then upload the resulting JSON files as artifacts.

```yaml
- name: Refresh and snapshot clusters
  run: |
    gitcrawl init --portable-store $PORTABLE_STORE_URL
    gitcrawl refresh openclaw/gitcrawl --json > sync.json
    gitcrawl clusters openclaw/gitcrawl --json --sort size --min-size 5 > clusters.json
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

- uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
  with: { name: triage, path: "*.json" }
```

--------------------------------

### Example JSON sync output

Source: https://gitcrawl.sh/sync

The standard JSON output format returned by the sync command when --json is specified.

```json
{
  "repository": "owner/repo",
  "threads_synced": 124,
  "issues_synced": 100,
  "pull_requests_synced": 24,
  "comments_synced": 0,
  "metadata_only": true,
  "started_at": "2026-05-05T07:30:11Z",
  "finished_at": "2026-05-05T07:30:43Z"
}
```

--------------------------------

### gitcrawl clusters-report usage examples

Source: https://gitcrawl.sh/clustering

Shows usage of `gitcrawl clusters-report` with options for limiting rows, setting minimum size, and outputting JSON. The Markdown report includes an at-a-glance table, per-cluster metadata, member tables, and key snippets.

```bash
gitcrawl clusters-report owner/repo --limit 10 --min-size 5
gitcrawl clusters-report owner/repo --json
```

--------------------------------

### gitcrawl clusters usage examples

Source: https://gitcrawl.sh/clustering

Shows basic usage of `gitcrawl clusters` with options for sorting by size or recent, setting a minimum size, and hiding closed clusters. The command displays clusters from the latest raw run, merging closed durable rows as historical context.

```bash
gitcrawl clusters owner/repo
gitcrawl clusters owner/repo --sort size --min-size 5
gitcrawl clusters owner/repo --sort recent
gitcrawl clusters owner/repo --hide-closed
```

--------------------------------

### Build from Source

Source: https://gitcrawl.sh/installation

Clone the repository and build the binary using Go.

```bash
git clone https://github.com/openclaw/gitcrawl.git
cd gitcrawl
go build \
  -ldflags "-X github.com/openclaw/gitcrawl/internal/cli.version=$(git describe --tags --always --dirty)" \
  -o bin/gitcrawl ./cmd/gitcrawl

./bin/gitcrawl --version
```

--------------------------------

### Initialize and verify Gitcrawl environment

Source: https://gitcrawl.sh/maintainer-archive

Run the initialization and diagnostic commands to ensure the environment is set up correctly.

```bash
gitcrawl init
gitcrawl doctor --json
```

--------------------------------

### Example JSON output for member exclusion

Source: https://gitcrawl.sh/governance

The expected JSON structure representing a member exclusion override.

```json
{
  "repository": "owner/repo",
  "override": { "cluster_id": 42, "thread_number": 456, "kind": "exclude", "reason": "different repro", "created_at": "..." },
  "excluded": true
}
```

--------------------------------

### Initialize gitcrawl with a portable store

Source: https://gitcrawl.sh/portable-stores

Use the init command to point gitcrawl at a portable store repository and specify the database file path.

```bash
gitcrawl init \
  --portable-store https://github.com/openclaw/gitcrawl-store.git \
  --portable-db data/openclaw__openclaw.sync.dbCopy
```

--------------------------------

### Run sync and capture

Source: https://gitcrawl.sh/capture

Run a successful all-state sync with comments before capturing. The capture command reads the local database and does not call GitHub. Keep --state all and --include-comments for incremental syncs; add --since to bound the GitHub update window.

```bash
gitcrawl sync owner/repo --state all --include-comments
gitcrawl capture owner/repo --output capture.json
```

--------------------------------

### Launch gitcrawl tui with various options

Source: https://gitcrawl.sh/tui

Shows common ways to launch the `gitcrawl tui` command. The first command opens a specific repository. The `--no-color` flag disables terminal colors. Without arguments, it infers the most recently updated local repo. `--min-size 5` is the default and shows clusters with at least 5 active members. `--sort recent` changes the ordering, `--layout focus` uses a wider detail pane, and `--hide-closed` focuses only on open clusters.

```bash
gitcrawl tui owner/repo
gitcrawl --no-color tui owner/repo # disable terminal colors
gitcrawl tui                      # infers the most recently updated local repo
gitcrawl tui --min-size 5         # default; show clusters with ≥5 active members
gitcrawl tui --sort recent        # alternate sort
gitcrawl tui --layout focus       # wider detail pane with members below
gitcrawl tui --hide-closed        # focus only on currently open clusters
```

--------------------------------

### Initialize and check local health with gitcrawl init, status, and doctor

Source: https://gitcrawl.sh/maintainer-archive

Initializes or verifies the runtime before spending GitHub quota. `status --json` reports the configured archive database and its repository/thread/open-thread/cluster inventory under `databases[].counts`, plus `last_sync_at` and `last_export_at`. `doctor --json` reports config path, database health, credential discovery, model settings, portable-store status, and the same core counts.

```bash
gitcrawl init
gitcrawl status --json
gitcrawl doctor --json
```

--------------------------------

### gitcrawl threads command for local discovery

Source: https://gitcrawl.sh/gh-shim

Use this command to keep local discovery in Gitcrawl, fetching thread numbers with closed issues included and JSON output. It is part of the existing Octopool setup workflow.

```bash
gitcrawl threads owner/repo --numbers 123 --include-closed --json
```

--------------------------------

### octopool gh api command for pull request access

Source: https://gitcrawl.sh/gh-shim

Use this command to access a pull request via the Octopool API. It is part of the first-time Octopool setup workflow, and is shown with a specific repository and pull request number.

```bash
octopool gh api repos/openclaw/openclaw/pulls/85341
```

--------------------------------

### Find, hydrate, and summarize candidates

Source: https://gitcrawl.sh/automation

Search for issues locally, sync specific numbers with comments and PR details, then retrieve cluster details.

```bash
NUMS=$(gitcrawl search issues "checksum mismatch" -R owner/repo \
        --json number --limit 30 \
        | jq -r '[.[].number] | join(",")')

gitcrawl sync owner/repo --numbers "$NUMS" --include-comments --with pr-details

gitcrawl cluster-detail owner/repo --id "$(gitcrawl clusters owner/repo --json \
        | jq '.clusters[0].id')"
```

--------------------------------

### Looping over repositories in shell

Source: https://gitcrawl.sh/automation

Iterate through a list of repositories and process each with gitcrawl and jq.

```bash
for repo in openclaw/gitcrawl steipete/repo-a octocat/repo-b; do
  gitcrawl refresh "$repo" --json | jq '{repo: "'"$repo"'", sync: .sync, embed: .embed}'
done
```

--------------------------------

### JSON output of gitcrawl search in hybrid mode

Source: https://gitcrawl.sh/search

Displays the JSON output format for gitcrawl search results, including repository, query, mode, and hits array with issue/PR metadata. The example shows the expected structure when --json is used.

```json
{
  "repository": "owner/repo",
  "query": "download stalls",
  "mode": "hybrid",
  "hits": [
    { "number": 123, "kind": "issue", "title": "...", "score": 0.81, "url": "...", "updated_at": "..." }
  ]
}
```

--------------------------------

### gh pr view command for fresh PR metadata

Source: https://gitcrawl.sh/gh-shim

Use this bare PATH gh command to view PR details with JSON output. It is part of the existing Octopool setup workflow, and uses native field names like headRefName and headRefOid.

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

--------------------------------

### Sync with time-windowed constraints and state filter

Source: https://gitcrawl.sh/sync

Combine --since and --state flags to tightly scope the synchronization process.

```bash
gitcrawl sync owner/repo --state all --since 2026-04-01T00:00:00Z
```

--------------------------------

### gh pr checks command for PR check status

Source: https://gitcrawl.sh/gh-shim

Use this bare PATH gh command to view PR check status with JSON output. It is part of the existing Octopool setup workflow, and uses native field names like bucket and link.

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

--------------------------------

### Set credentials in config.toml

Source: https://gitcrawl.sh/quickstart

Alternatively, store your API keys directly in the configuration file.

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

--------------------------------

### gitcrawl init default config.toml

Source: https://gitcrawl.sh/configuration

Minimal configuration written by `gitcrawl init`. Edit by hand or with `gitcrawl configure`. Includes model settings, environment variables, portable store, and remote archive configuration.

```toml
summary_model = "gpt-5.4"
embed_model = "text-embedding-3-small"
embed_dimensions = 1024
embedding_basis = "title_original"
vector_backend = "exact"

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

[portable_store]
url = "https://github.com/org/portable-store.git"
db_path = "data/openclaw__openclaw.sync.db"
checkout_dir = "/Users/me/Library/Application Support/gitcrawl/stores/portable-store"

[remote]
mode = "cloud"
endpoint = "https://crawl.example.com"
archive = "gitcrawl/org__repo"
token_env = "CRAWL_REMOTE_TOKEN"
```

--------------------------------

### Set credentials via environment variables

Source: https://gitcrawl.sh/quickstart

Export the required GitHub and OpenAI API keys in your shell session.

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

--------------------------------

### Read candidates and perform live GitHub actions

Source: https://gitcrawl.sh/maintainer-archive

Read exact candidates with gitcrawl and use the bare PATH gh for live reads and writes.

```bash
gitcrawl threads --numbers
```

--------------------------------

### Sync a repository

Source: https://gitcrawl.sh/quickstart

Fetch issues and pull requests for a repository. Use the --numbers flag to sync specific items.

```bash
gitcrawl sync openclaw/gitcrawl
```

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

--------------------------------

### Embed and cluster repository data

Source: https://gitcrawl.sh/quickstart

Run the full sync, embed, and cluster pipeline end-to-end.

```bash
gitcrawl refresh openclaw/gitcrawl
```

--------------------------------

### Use managed GitHub credentials with --github-token-command

Source: https://gitcrawl.sh/configuration

Select a trusted executable for managed GitHub credentials. The executable must print exactly one nonempty token line to stdout and is invoked before each GitHub HTTP dispatch. This mode is Unix-only; Windows returns an unsupported-platform error.

```bash
gitcrawl --github-token-command /usr/local/bin/github-token sync owner/repo --state all
```

--------------------------------

### Publishing a portable store

Source: https://gitcrawl.sh/portable-stores

The standard workflow for refreshing upstream data, pruning the database for a smaller footprint, and pushing the changes to a Git repository.

```bash
# In the portable store checkout, refresh upstream data into the local runtime mirror.
gitcrawl refresh owner/repo

# Prune for a small, shareable footprint and publish the database plus manifest into the checkout.
gitcrawl portable prune --body-chars 256

# Commit and push using normal Git from the configured portable checkout.
cd ~/Library/Application\ Support/gitcrawl/stores/gitcrawl-store
# Linux default: cd ~/.config/gitcrawl/stores/gitcrawl-store
git add data/openclaw__openclaw.sync.db data/openclaw__openclaw.sync.db.manifest.json
git commit -m "data: refresh openclaw/gitcrawl"
git push
```

--------------------------------

### Combining search with sync: hydrate candidates in one round-trip

Source: https://gitcrawl.sh/search

A three-step discovery pattern: (1) find candidate numbers locally via gitcrawl search, (2) hydrate with sync including comments and PR details, (3) re-query with full context via gitcrawl tui or open in TUI.

```shell
# 1. Find candidates locally.
NUMS=$(gitcrawl search issues "download stalls" -R owner/repo \
        --json number --limit 20 \
        | jq -r '[.[].number] | join(",")')

# 2. Hydrate them with comments + PR detail in one round-trip.
gitcrawl sync owner/repo --numbers "$NUMS" --include-comments --with pr-details

# 3. Re-query with full conversational context (or open in TUI).
gitcrawl tui owner/repo
```

--------------------------------

### Search with --sync-if-stale 5m

Source: https://gitcrawl.sh/automation

Runs a search with a staleness bound: if the local mirror is older than 5 minutes, it syncs first. Best for ad-hoc agent tools that should minimize sync calls while bounding staleness.

```bash
gitcrawl search issues "manifest cache" \
  -R owner/repo \
  --sync-if-stale 5m \
  --json number,title,url
```

--------------------------------

### Dispatch release workflow via GitHub CLI

Source: https://gitcrawl.sh/releasing

Use the GitHub CLI to trigger the official release workflow for a specific version.

```bash
gh workflow run release-unified.yml --repo openclaw/gitcrawl -f version=X.Y.Z
```
Tokens:
Raw