GitContribute

Find better open-source contributions—with evidence, not guesswork.

GitContribute is a local-first research workbench for discovering, investigating, validating, and preparing focused GitHub contributions.

Quick start · How it works · CLI guide · MCP · Safety · Contributing

Important

GitContribute never writes to GitHub. It syncs public or authenticated read-only data, keeps research on your machine, and prepares local drafts for you to review.

Why GitContribute?

Finding an issue is easy. Finding a contribution that is useful, unclaimed, appropriately scoped, and backed by evidence is the hard part.

GitContribute gives developers and coding agents a durable SQLite corpus of repositories, issues, pull requests, reviews, code snapshots, and research artifacts. Network access is always explicit. Once data is synced, search, inspection, health analysis, dossiers, and investigations run entirely offline.

	Capability	What it gives you
🔎	Typed offline search	Search repositories, issues, PRs, threads, and indexed code with transparent ranking.
📡	Contribution Radar	Rank promising open issues with explicit positives, risks, blockers, confidence, and missing-evidence warnings.
🗂️	Durable research corpus	Keep observations, coverage, investigations, evidence, and outcomes in local SQLite.
🧭	Contribution workflow	Move from hypothesis to opportunity, workspace, validation, readiness checks, and a prepared issue, PR, or review.
🤖	Agent-ready MCP server	Give Codex or Claude Code structured tools and resources with explicit capability boundaries.
🛡️	Safe by default	Separate network reads, local writes, process execution, and GitHub mutation.

⚡ Quick start

Run the guided setup with Node.js 18 or newer:

npx gitcontribute setup

The wizard shows the resolved GitContribute version before any choice.

The interactive wizard offers three access modes:

MCP — installs a private native runtime and configures selected coding agents;
CLI — installs the persistent gitcontribute command and TUI;
Both — installs the CLI and uses that verified executable for MCP.

The wizard displays detected coding agents without treating detection as permission to modify them. Existing GitContribute registrations may be preselected; new targets require an explicit selection. GitHub authentication is chosen from described options rather than typed internal identifiers. A dry-run plan shows every effect before final confirmation, which defaults to apply.

npx only bootstraps the wizard. MCP configuration never records npx, an npm cache path, or @latest: it points to an absolute native executable managed by GitContribute.

If you chose MCP, restart the selected coding agent and use GitContribute there. If you chose CLI or Both, launch the TUI, sync a repository, rank contribution candidates, and search the local corpus:

gitcontribute tui
gitcontribute sync owner/repo
gitcontribute radar owner/repo --limit 10
gitcontribute search threads "connection timeout" \
  --repo owner/repo --json
gitcontribute dossier build owner/repo --json

setup initializes the corpus, helps select a GitHub authentication source, can install the CLI or a private MCP runtime, and can register the MCP server with Codex and Claude Code. Adding a repository during setup does not contact GitHub or begin a sync.

For non-interactive setup, select the access mode explicitly:

# Both: CLI and Codex MCP
npx gitcontribute setup --mode both --codex --token-source none --yes

# CLI only
npx gitcontribute setup --mode cli --token-source none --yes

# MCP only; installs a private runtime without a global command
npx gitcontribute setup --mode mcp --codex --token-source none --yes

MCP-only setup is used through the configured coding agent. Run setup again and choose CLI or Both if you also want the gitcontribute terminal command.

Other installation options

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 selected MCP registrations. It does not delete versioned private runtimes, uninstall the CLI, or remove application configuration or corpus data.

Pin a project version

npm install --save-dev gitcontribute
npx gitcontribute setup --mode mcp --codex --token-source none --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

You need git. The gh CLI is optional and can provide authentication through gh auth token; ripgrep is optional and adds an extra doctor check.

🧩 How it works

 GitHub read APIs                  Local checkout
       │                                │
       │ explicit sync / hydrate        │ explicit index / acquire
       ▼                                ▼
  ┌──────────────────────────────────────────┐
  │          Local SQLite corpus             │
  │ observations · projections · coverage   │
  │ investigations · evidence · outcomes    │
  └────────────────────┬─────────────────────┘
                       │ offline reads
          ┌────────────┼─────────────┐
          ▼            ▼             ▼
       CLI / TUI    MCP agents    JSON exports

1. Discover

Track explicit repositories, GitHub search results, or GH Archive event streams. Sync only when you ask, then search locally as often as you like.

gitcontribute source add repos --name my-go "golang/go" "cli/cli" --json
gitcontribute crawl my-go --since 720h --budget 500 --json
gitcontribute radar golang/go --limit 20 --json
gitcontribute search issues "data race" --repo golang/go --state open --json
gitcontribute search code "context.WithTimeout" --repo golang/go

2. Investigate

Build a dossier or per-thread research brief, inspect repository health, record a hypothesis, and check for duplicate or competing work before committing time.

gitcontribute dossier build owner/repo
gitcontribute research brief issue:owner/repo#42 --format markdown
gitcontribute health owner/repo --json
gitcontribute investigation start-thread issue:owner/repo#42 --json
gitcontribute duplicates check <hypothesis-id>
gitcontribute collisions check <hypothesis-id>

3. Validate

Promote promising research into an opportunity, create an isolated worktree, record evidence, and compare a baseline with your candidate change.

gitcontribute opportunity promote --problem="Retry can hang indefinitely" \
  --scope=small --impact="reduces flakes" --effort=1h \
  --confidence=0.8 <hypothesis-id>
gitcontribute workspace create <investigation-id>
gitcontribute validation define --kind=test --command="go test ./..." \
  --working-dir=/path/to/workspace <investigation-id>
gitcontribute validation run <validation-id> --kind=base --execute
gitcontribute validation run <validation-id> --kind=candidate --execute
gitcontribute validation compare <base-run-id> <candidate-run-id>

4. Check readiness

Run a deterministic local readiness gate before turning a candidate into a public submission:

gitcontribute readiness opportunity <opportunity-id>
gitcontribute readiness explain <opportunity-id>:evidence_freshness

Readiness reports pass, warn, block, or unknown per rule. It only reads stored corpus and draft metadata: it does not fetch GitHub, execute validation, write state, or infer that missing coverage is a hard blocker.

5. Prepare

Create a local contribution draft from the evidence and workspace diff:

gitcontribute prepare issue <opportunity-id>
gitcontribute prepare pr --approach="Bound retries with context" \
  --workspace <workspace-id> <opportunity-id>
gitcontribute prepare review <opportunity-id>

Nothing is posted. You decide what leaves your machine.

🤖 Use with AI agents

The MCP server gives agents structured access to the same corpus and workflow:

gitcontribute setup --mode mcp --codex --token-source none --yes
gitcontribute setup --mode mcp --all-clients --token-source none --yes

Or start the stdio server directly:

gitcontribute mcp serve --transport=stdio

MCP capabilities are deliberately separate:

Tool names use the <capability>.<action> namespace. MCP clients qualify them with the configured gitcontribute server name, producing names such as gitcontribute.corpus.search_repositories. The server advertises one canonical name per operation; unnamespaced compatibility aliases are not registered.

Capability	Examples
Offline reads	Batch-inspect repositories, threads, and jobs; filter open or closed work; rank opportunities across repositories; find historical precedents; and review the authored pull-request portfolio.
Network reads	Batch-sync repository metadata or thread headers, hydrate selected finalists, discover authored pull requests, refresh PR status, and query derived public-repository context through DeepWiki.
Local writes	Start investigations, record hypotheses, promote opportunities, define validations, and prepare drafts.
Execution	Safely acquire and index repository code with Git only, or run a validation only when the request includes `execute: true`.

A scalable discovery flow is:

github.search_repositories -> corpus.get_repositories
github.sync_repository_metadata -> corpus.get_repositories
-> research.query_deepwiki -> github.sync_threads
-> corpus.rank_threads -> github.hydrate_threads
-> corpus.find_precedents

For contribution follow-up, use github.sync_authored_pull_requests, then github.sync_pull_request_status and corpus.list_pull_request_portfolio. Missing coverage is returned as unknown rather than as a false zero or negative. PR status currently includes lifecycle, mergeability, head/base revisions, and stored reviews. Checks, unresolved review threads, detailed merge state, merge queue, and portfolio overlap are deliberately reported as unavailable. See the scalable MCP workflow guide for recovery and coverage details.

Contribution workflow resources and prompts are available for agents:

corpus.get_readiness and gitcontribute://readiness/<opportunity-id> expose the same offline readiness report as the CLI.
gitcontribute://workflow/contribution/<opportunity-id> links the local opportunity, evidence, readiness report, and safe workflow prompts.
Prompts such as review_contribution_readiness instruct agents to treat repository and GitHub-sourced text as untrusted data and to ask before any network read, local write, or validation execution.

Resources are published under gitcontribute:// and github-index:// URI schemes. See the architecture guide for the complete application and adapter boundaries.

🛡️ Safety by design

Operation	Network	Local write	Runs a process	GitHub write
Search, health, dossier, research-brief, and readiness inspection	—	—	—	—
Investigations, evidence, lenses	—	✓	—	—
Sync, crawl, hydrate	✓	✓	—	—
DeepWiki repository context	✓	—	—	—
Acquire and batch-index code	✓	✓	`git` only	—
Acquire or create a workspace	remote-dependent	✓	`git` only	—
Validation with explicit execution	— by default	✓	✓	—

No GitHub writes. GitContribute does not open issues, create pull requests, push commits, or mutate GitHub.
No hidden network access. Corpus reads never fetch data.
No hosted service or telemetry. Your corpus and research remain local.
No automatic repository execution. Crawling and indexing never execute repository-controlled code.
No implied sandbox. Explicit validation commands run on your host with the permissions of your user and only the environment variables you allowlist.
No opaque semantic ranking. Search uses SQLite FTS5 and reports signals such as text matches, freshness, and coverage.

📚 CLI guide

The sections below are a task-oriented reference. Run gitcontribute --help or gitcontribute <command> --help for every flag.

Setup, configuration, and authentication

gitcontribute setup                              # interactive
gitcontribute setup --mode mcp --codex --token-source none --yes
gitcontribute setup --mode mcp --all-clients --token-source none --yes
gitcontribute setup --mode mcp --codex --token-source env \
  --token-source-key GITHUB_TOKEN --yes
gitcontribute setup --mode mcp --codex --token-source none --dry-run --json
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. metadata reports the schema of an existing corpus through a read-only check; it does not create the database or apply migrations when invoked by itself. Use gitcontribute doctor --strict in automation when unhealthy required checks should produce a non-zero exit status. Write contention is reported as an optional availability warning rather than database corruption.

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

Sources, crawling, sync, and hydration

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 --max-requests 100
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; issue_timeline is available only when explicitly requested. Fetches are paginated and cancellation-aware; a complete facet replaces its previous snapshot atomically.

Complete comment, review, review-comment, and explicitly requested timeline snapshots also enrich offline thread search. Results identify the stored facet in match_source and include a bounded match_excerpt; API page boundaries do not change matching semantics. Repository-controlled discussion remains untrusted evidence and is never executed.

Code indexing and acquisition

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.

Radar, research briefs, search, dossiers, health, seeds, and lenses

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

Thread search covers stored titles and bodies plus searchable evidence from complete hydrated discussion and timeline snapshots. Facet-backed matches report where the term was found instead of returning an unexplained thread.

seeds defaults to accepted (positive) and constraining (negative) outcome evidence so recent open issues cannot crowd historical examples out of the result limit. Merged PRs are positive; observed closed-unmerged PRs are negative. Issues remain context unless GitHub records not_planned or a predefined rejection/supersession label (duplicate, wontfix, not planned, superseded, invalid, or rejected). Select context explicitly when you want problem statements rather than implementation outcomes:

gitcontribute seeds owner/repo --polarity=context --from=issues --json

radar is a strict offline corpus read. It ranks a bounded population of the newest stored open issues and separates the numeric score from four explicit eligibility states: ready_to_code, needs_diagnosis, needs_coordination, and blocked. Its required repository argument is always positional, and one run can return up to the complete 500-candidate population. Every candidate reports positive signals, risks, blockers, confidence, linked open PRs, evidence coverage, and unknowns. An explicit sync ingests a fixed, bounded set of conventional CONTRIBUTING and AI-policy files; hydrate comments when you want maintainer-direction and recent-claim evidence:

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

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

The cross-repository MCP Radar requires an explicit repository list and is a bounded, non-paginated derived ranking. Its total and truncated fields make omitted candidates visible; increase the limit or narrow the repository set rather than reusing a search cursor. Per-repository summaries separate considered, returned, and internally capped populations.

Radar's related_work facts unify stored PR mentions and closing relationships, issue/comment dependencies, timeline cross-references, and duplicate clusters. Every relationship keeps its source kind and URL. An open PR that GitHub says closes the issue is an implementation blocker; other open dependencies and related PRs require coordination instead of being mislabeled as completed work.

Thread sync stores issue and pull-request headers without implicitly hydrating each pull request. A sync has a total GitHub request budget (100 by default), reported in JSON and run statistics; page bounds and the request budget both prevent broad repository or batch inputs from producing hidden N+1 traffic. Generated network remediation commands include explicit request/page bounds.

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.

Investigations, evidence, tracking, and collections

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.

Workspaces, jobs, runs, and TUI

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.

JSON and output behavior

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>.

💾 Storage locations

Platform	Config	Data	Cache	Logs
Linux / Unix	`$XDG_CONFIG_HOME/gitcontribute` or `~/.config/gitcontribute`	`$XDG_DATA_HOME/gitcontribute` or `~/.local/share/gitcontribute`	`$XDG_CACHE_HOME/gitcontribute` or `~/.cache/gitcontribute`	`$XDG_STATE_HOME/gitcontribute` or `~/.local/state/gitcontribute/logs`
macOS	`~/Library/Application Support/gitcontribute`	`~/Library/Application Support/gitcontribute/Data`	`~/Library/Caches/gitcontribute`	`~/Library/Logs/gitcontribute`
Windows	`%APPDATA%\gitcontribute`	`%LOCALAPPDATA%\gitcontribute\Data`	`%LOCALAPPDATA%\gitcontribute\Cache`	`%LOCALAPPDATA%\gitcontribute\Logs`

The default database is gitcontribute.db in the data directory. The configuration file is config.toml in the config directory.

🖥️ Platform support

Linux and macOS are the primary development and test targets. Windows builds are expected to work with Git for Windows and standard %APPDATA% and %LOCALAPPDATA% paths. For platform-specific problems, open a bug report with the output of gitcontribute doctor --json.

🛠️ Development

go test ./...
go build -o gitcontribute ./cmd/gitcontribute
./gitcontribute --help

Before changing package boundaries or side effects, read docs/architecture.md. See CONTRIBUTING.md for the complete development and testing workflow.

Built for contributors who want to understand the problem before writing the patch.

Architecture · Onboarding · Runbooks · Security · Contributing · License

Name		Name	Last commit message	Last commit date
Latest commit History 238 Commits
.codex/complexity-root-redesign		.codex/complexity-root-redesign
.devcontainer		.devcontainer
.factory		.factory
.github		.github
LICENSES		LICENSES
cmd/gitcontribute		cmd/gitcontribute
docs		docs
internal		internal
npm		npm
scripts		scripts
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CONTEXT.md		CONTEXT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
cliff.toml		cliff.toml
go.mod		go.mod
go.sum		go.sum
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

GitContribute

Find better open-source contributions—with evidence, not guesswork.

Why GitContribute?

⚡ Quick start

Install a persistent command

Pin a project version

Build from source

🧩 How it works

1. Discover

2. Investigate

3. Validate

4. Check readiness

5. Prepare

🤖 Use with AI agents

🛡️ Safety by design

📚 CLI guide

💾 Storage locations

🖥️ Platform support

🛠️ Development

About

Uh oh!

Releases 11

Packages

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

GitContribute

Find better open-source contributions—with evidence, not guesswork.

Why GitContribute?

⚡ Quick start

Install a persistent command

Pin a project version

Build from source

🧩 How it works

1. Discover

2. Investigate

3. Validate

4. Check readiness

5. Prepare

🤖 Use with AI agents

🛡️ Safety by design

📚 CLI guide

💾 Storage locations

🖥️ Platform support

🛠️ Development

About

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages