gitcontribute

Install a persistent command

npm install --global gitcontribute@latest
gitcontribute setup

To remove a global npm installation later, run npm uninstall --global gitcontribute. The gitcontribute remove command only removes MCP registrations; it does not uninstall the terminal app.

Pin a project version

npm install --save-dev gitcontribute
npx gitcontribute setup --codex --yes

The npm package has no install lifecycle and performs no download during installation. Native binaries are included for macOS ARM64/x64, Linux ARM64/x64, and Windows x64.

Build from source

Developers with Go 1.26 or newer can install or build the CLI directly:

go install github.com/morluto/gitcontribute/cmd/gitcontribute@latest
go build -o gitcontribute ./cmd/gitcontribute

gitcontribute setup                              # interactive
gitcontribute setup --codex --yes               # configure Codex
gitcontribute setup --all-clients --yes          # configure supported clients
gitcontribute setup --codex --mcp-version latest --yes
gitcontribute setup --token-source env \
  --token-source-key GITHUB_TOKEN --yes
gitcontribute setup --codex --dry-run --json     # inspect without writing
gitcontribute remove --all-clients --yes         # remove MCP registrations only
gitcontribute upgrade --check
gitcontribute upgrade --yes

gitcontribute init creates the default database and directories without contacting GitHub. gitcontribute configure updates config.toml atomically:

gitcontribute configure --database /path/to/corpus.db
gitcontribute configure --token-source env --token-source-key GITHUB_TOKEN
gitcontribute configure --token-source gh-cli
gitcontribute configure --output-format json

Authentication sources are none, env, gh-cli, and keyring. Tokens are resolved at runtime and are never stored in the corpus or logs. Use gitcontribute status, metadata, and doctor to inspect the local setup.

See the onboarding design for the full contract and environment-variable reference.

Add a source:

gitcontribute source add repos --name my-go "golang/go" "cli/cli" --json
gitcontribute source add search --name go-network \
  --query "language:go stars:>100" --json
gitcontribute source add gharchive --name golang-events \
  --events "IssuesEvent,PullRequestEvent" --json

Run it once or continuously:

gitcontribute crawl golang-events --since 720h --budget 500 --json
gitcontribute tail golang-events --since 2h --budget 500 --interval 1h

Sync and selectively hydrate repository archives:

gitcontribute sync owner/repo
gitcontribute archive sync owner/repo --since 168h --state open
gitcontribute archive sync owner/repo --numbers 42,108
gitcontribute archive refresh owner/repo
gitcontribute archive hydrate owner/repo#42 --with issue_comments
gitcontribute archive hydrate owner/repo#108 \
  --with pr_reviews,pr_review_comments
gitcontribute archive coverage owner/repo

Hydration supports issue_comments, pr_details, pr_reviews, and pr_review_comments. Fetches are paginated and cancellation-aware; a complete facet replaces its previous snapshot atomically.

Index a clean local checkout at its current commit:

gitcontribute index owner/repo /path/to/checkout --json

Or acquire a repository into a managed mirror, index a clean temporary worktree, and remove that worktree afterward:

gitcontribute acquire owner/repo \
  --remote https://github.com/owner/repo.git --json

The indexer reads blobs directly from Git, skips binaries and non-UTF-8 content, enforces size limits, and rejects dirty worktrees.

gitcontribute radar owner/repo --limit 20
gitcontribute search repos "cli" --limit 20 --json
gitcontribute search issues "data race" --repo owner/repo --state open --json
gitcontribute search prs "flaky" --repo owner/repo --label bug --json
gitcontribute search threads "memory leak" --repo owner/repo
gitcontribute search code "context.WithTimeout" --repo owner/repo
gitcontribute search all "retry" --repo owner/repo

gitcontribute dossier build owner/repo
gitcontribute dossier export owner/repo --format markdown \
  --output owner-repo-dossier.md
gitcontribute research brief owner/repo#42
gitcontribute research brief pr:owner/repo#108 --json
gitcontribute health owner/repo --stale-after 336h --json
gitcontribute seeds owner/repo --json

radar is a strict offline corpus read. It ranks a bounded population of the newest stored open issues and separates objective eligibility from the numeric score. Every candidate reports positive signals, risks, blockers, confidence, linked open PRs, evidence coverage, and unknowns. Missing comment coverage is reported as unknown and does not lower the score; hydrate comments explicitly when you want that evidence:

gitcontribute archive hydrate owner/repo#42 --with issue_comments
gitcontribute radar owner/repo --json

Radar scores carry a version (radar.v1) so saved JSON remains auditable when ranking semantics evolve. It never syncs, hydrates, executes repository code, or writes to GitHub.

research brief is also a strict offline read. Its versioned research-brief.v1 output has fixed sections for state, stored problem fields, acceptance hints, participants, timeline, explicit/duplicate references, linked PRs, indexed code, contribution guidance, health, coverage gaps, and next commands. Every section carries source references or an explicit unknown reason. Checkboxes and maintainer phrases remain source extracts—not fabricated or complete acceptance criteria. Markdown output redacts common credentials and quotes untrusted source text; JSON ordering is deterministic.

Missing child facets and code stay visible instead of triggering hidden work:

gitcontribute archive hydrate owner/repo#42 --with issue_comments
gitcontribute index owner/repo /path/to/clean-checkout
gitcontribute research brief issue:owner/repo#42 --json

Use a lens to apply saved filters and weighted ranking to a bounded population:

gitcontribute lens add my-lens --file lens.json
gitcontribute search issues "retry" --lens my-lens
gitcontribute lens explain my-lens issue:owner/repo#42 --query "retry"

Search results explain their scores. Most typed searches support opaque cursor pagination; search all and lens-ranked searches do not.

Start an investigation and its initial hypothesis from one exact stored thread revision:

gitcontribute investigation start-thread issue:owner/repo#42 --json

This is a local-write operation with no network or process execution. The investigation saves the immutable observation ID, source update time, sequence, and source reference used for its title and bounded description. Repeating the command returns the existing open pair with "created": false; it never updates that baseline silently. The seed category is other because the command does not infer scope or defect type from untrusted issue text.

The manual two-command path remains available when no stored thread should be the baseline:

gitcontribute investigation start owner/repo --json
gitcontribute hypothesis add --title="Fix retry timeout" \
  --description="Reproduce and isolate the timeout." \
  --category=bug <investigation-id>

Record supporting or contradicting evidence:

gitcontribute evidence add --type=manual_observation --relation=supporting \
  --description="Reproduced on the current default branch." \
  --opportunity <opportunity-id>

Evidence shown through the CLI, exports, and MCP includes a derived freshness status. github_source evidence recorded from a started thread carries the exact corpus source revision it used, so later issue, pull request, facet, or guidance updates can mark it stale. Missing source projections are unknown; local/manual evidence is not_applicable. Freshness is evaluated from local corpus reads only, and stale evidence is a prompt to re-check, not a claim that the evidence is invalid.

Group typed references and record local decisions:

gitcontribute collection create interesting
gitcontribute collection add interesting \
  repo:owner/repo issue:owner/repo#42
gitcontribute triage record issue:owner/repo#42 viewed --reason "..."
gitcontribute contribution record <opportunity-id> issue \
  "Draft title" --body "..."
gitcontribute contribution outcome <contribution-id> submitted

Export and restore tracking metadata:

gitcontribute tracking export --output tracking.json
gitcontribute tracking import --file tracking.json

Tracking exports use schema version 2 for portable evidence provenance and remain backward compatible with older unversioned tracking bundles. Exports are redacted: they exclude credentials, tokens, and absolute local paths.

gitcontribute workspace show <workspace-id>
gitcontribute diff <workspace-id>
gitcontribute runs --limit 20
gitcontribute jobs
gitcontribute job show <id>
gitcontribute job cancel <id>
gitcontribute tui owner/repo

diff returns the patch, changed files, and suggested review order. The TUI is local-only; add --json to emit a non-interactive snapshot.

Most non-interactive commands accept --json. Machine-readable output goes to stdout; progress and status messages go to stderr. List commands accept --limit, and paginated searches return an opaque next_cursor where supported.

dossier export, export dossier, export evidence, and tracking export accept --output <file>.