gsoc-contrib (contrib)

A fast, lightweight contribution workspace manager for GitHub issues without repeatedly cloning entire multi-gigabyte repositories.

The Problem

When contributing to open-source repositories (such as during Google Summer of Code, Hacktoberfest, or day-to-day open-source work), developers frequently clone massive git repositories just to fix a single bug or submit a small pull request.

This leads to:

• Wasted Bandwidth: Downloading gigabytes of historical git blobs that are never touched.
• Wasted Disk Space: Storing duplicate monolithic repos for each separate issue.
• Slow Onboarding: Waiting minutes for git clone before writing a single line of code.

The Solution

gsoc-contrib (contrib) creates instant, isolated, lightweight workspaces for specific GitHub issues or pull requests using Git's blobless (--filter=blob:none) and sparse capabilities. It resolves issue metadata, sets up a dedicated branch, analyzes relevant source files, and tracks all your ongoing contributions from a single CLI.

Installation & Execution

Run instantly with npx (No install required)

npx gsoc-contrib <command>

Or install globally

npm install -g gsoc-contrib

Once installed globally, you can run either contrib or gsoc-contrib:

contrib --help

Quick Start

1. Initialize and Verify Environment

npx gsoc-contrib init

2. Match Skills with GSoC Organizations (AI Recommendation Quiz)

# Launch interactive GSoC project matcher:
npx gsoc-contrib recommend

# Or filter directly via CLI flags:
npx gsoc-contrib recommend --lang python,javascript --domain ai --level beginner

3. Search for Contribution Opportunities

npx gsoc-contrib search "good first issue" --repo psf/requests

3. Analyze an Issue Before Cloning

npx gsoc-contrib analyze https://github.com/psf/requests/issues/6000

4. Start a Contribution Workspace

npx gsoc-contrib start https://github.com/psf/requests/issues/6000

Or using shorthand:

npx gsoc-contrib contribute psf/requests#6000 -b fix-header-parsing

5. Open in Any Editor or Browser

# Open in Antigravity IDE (aliases: --agy, --ide)
npx gsoc-contrib open --antigravity

# Open in terminal power-user editors
npx gsoc-contrib open --nvim        # Neovim
npx gsoc-contrib open --vim         # Vim
npx gsoc-contrib open --helix       # Helix (--hx)
npx gsoc-contrib open --zed         # Zed

# Open in JetBrains or desktop editors
npx gsoc-contrib open --code        # Visual Studio Code
npx gsoc-contrib open --cursor      # Cursor
npx gsoc-contrib open --idea        # IntelliJ IDEA
npx gsoc-contrib open --pycharm     # PyCharm
npx gsoc-contrib open --webstorm    # WebStorm
npx gsoc-contrib open --subl        # Sublime Text

# Or open the issue in your default browser
npx gsoc-contrib open --web

# Or jump directly into the workspace using the 'gcd' shell shortcut!
gcd psf__requests__issue_6000

6. Set Up Shell Integration (gcd shortcut)

# Automatically install 'gcd' shortcut and completions into ~/.zshrc, ~/.bashrc, or $PROFILE:
npx gsoc-contrib alias --install

7. Sync with Upstream & Push to Your Fork

# Fetch upstream default branch, rebase feature branch, and push to your personal fork:
npx gsoc-contrib sync --fork

8. Check Active Workspaces

npx gsoc-contrib status

9. Clean Up When Done

npx gsoc-contrib cleanup psf__requests__issue_6000

CLI Commands

start <url>

Create or open a lightweight contribution workspace for a GitHub issue or PR URL.

# Using full URL (blobless mode by default)
npx gsoc-contrib start https://github.com/psf/requests/issues/6000

# Sub-second workspace creation via shared Git worktree
npx gsoc-contrib start https://github.com/psf/requests/issues/6000 --worktree

# Automatically configure upstream and personal fork remotes
npx gsoc-contrib start https://github.com/psf/requests/issues/6000 --fork

# Sparse checkout only focused directories
npx gsoc-contrib start https://github.com/psf/requests/issues/6000 --sparse src/requests

# Operate completely off-grid using local cached metadata and bare git clone
npx gsoc-contrib start https://github.com/psf/requests/issues/6000 --offline

# Apply Git & SSH identity to workspace
npx gsoc-contrib start https://github.com/psf/requests/issues/6000 --identity personal

# With custom branch name
npx gsoc-contrib start https://github.com/psf/requests/issues/6000 -b fix-bug-123

contribute <target>

Smart shorthand alias for starting a workspace. Supports full URLs, repository shorthands (owner/repo#123), and repo targets (owner/repo).

npx gsoc-contrib contribute facebook/react#24000 --worktree --fork

sync [id]

Pull upstream changes, rebase your local feature branch against upstream/main, and optionally push updated commits to your personal fork.

# Rebase feature branch on upstream/main
npx gsoc-contrib sync

# Rebase from upstream and push to personal fork (origin) in one action
npx gsoc-contrib sync --fork
npx gsoc-contrib sync -p

open [options] [id]

Open a contribution workspace directly in your preferred editor or launch the corresponding GitHub issue/PR in your browser.

# Auto-open active workspace in detected default editor
npx gsoc-contrib open

# Open in Antigravity IDE (aliases: --agy, --ide)
npx gsoc-contrib open psf/requests#6000 --antigravity

# Power-user editors
npx gsoc-contrib open psf/requests#6000 --nvim
npx gsoc-contrib open psf/requests#6000 --vim
npx gsoc-contrib open psf/requests#6000 --helix
npx gsoc-contrib open psf/requests#6000 --zed
npx gsoc-contrib open psf/requests#6000 --idea
npx gsoc-contrib open psf/requests#6000 --pycharm
npx gsoc-contrib open psf/requests#6000 --webstorm
npx gsoc-contrib open psf/requests#6000 --subl
npx gsoc-contrib open psf/requests#6000 --code
npx gsoc-contrib open psf/requests#6000 --cursor

# Open custom editor
npx gsoc-contrib open psf/requests#6000 --editor nano

# Open the issue specification (.contrib/ISSUE.md) directly
npx gsoc-contrib open psf/requests#6000 --issue

# Open the GitHub issue or PR in default browser
npx gsoc-contrib open psf/requests#6000 --web

# Print path only (for shell navigation/piping)
cd $(npx gsoc-contrib open psf/requests#6000 --print)

shell-init [shell] & alias

Native shell integration for instant workspace jumping via gcd and tab auto-completion across Bash, Zsh, Fish, and PowerShell.

# Quick session evaluation:
eval "$(npx gsoc-contrib shell-init zsh)"          # Zsh
eval "$(npx gsoc-contrib shell-init bash)"         # Bash
npx gsoc-contrib shell-init fish | source          # Fish
npx gsoc-contrib shell-init pwsh | Out-String | iex # PowerShell

# Or install permanently into shell profile:
npx gsoc-contrib alias --install

# Jump directly into any workspace!
gcd <workspace-id>

dashboard (aliases: dash, tui)

Launch the interactive full-screen TUI workspace dashboard. Zero third-party dependencies, instant load times, and single-keystroke navigation.

# Launch the interactive terminal UI
npx gsoc-contrib dashboard

# Or shorthand
npx gsoc-contrib dash

• Keyboard Navigation:
  • ↑ / k or ↓ / j: Move cursor up and down through active workspaces.
  • Enter or o: Open workspace in default editor.
  • a: Open in Antigravity IDE.
  • c: Open in Visual Studio Code.
  • n: Open in Neovim.
  • s: Sync with upstream and rebase feature branch.
  • d: View interactive git diff.
  • x: Clean up workspace safely.
  • q / Esc: Exit dashboard.

identity [action] [name]

Manage multiple Git/SSH identities and switch them across contribution workspaces. Never accidentally commit with your corporate email again!

# 1. Add identities
npx gsoc-contrib identity add personal \
  --name "Anand M" \
  --email "[email protected]" \
  --ssh-host "github-personal"

npx gsoc-contrib identity add work \
  --name "Anand M (Enterprise)" \
  --email "[email protected]"

# 2. List configured identities
npx gsoc-contrib identity list

# 3. Apply an identity when creating a workspace
npx gsoc-contrib start facebook/react#24000 --identity personal

# 4. Switch identity in an existing workspace
npx gsoc-contrib identity use work

# 5. Remove an identity
npx gsoc-contrib identity remove work

stats

View contribution metrics, active workspaces, and commits authored. Useful for GSoC/Hacktoberfest check-in reports.

# Terminal summary
npx gsoc-contrib stats

# Export Markdown table for reports
npx gsoc-contrib stats --markdown

submit [id] (alias: pr)

Inspect your workspace's branch status, verify uncommitted changes, and prepare a GitHub Pull Request with auto-generated titles, issue linkage (Fixes #123), and compare URLs.

npx gsoc-contrib submit

status

List all active workspaces, their corresponding repositories, active branches, local paths, clone modes, and disk usage.

npx gsoc-contrib status

cleanup [id]

Safely delete a contribution workspace and remove it from the workspace registry. Protects uncommitted work unless --force is provided.

# Delete a specific workspace (prompts for confirmation)
npx gsoc-contrib cleanup psf__requests__issue_6000

# Delete without prompt
npx gsoc-contrib cleanup psf__requests__issue_6000 -y

# Force delete workspace even if uncommitted changes exist
npx gsoc-contrib cleanup psf__requests__issue_6000 -f

# Clean up all workspaces safely (skips dirty workspaces unless -f)
npx gsoc-contrib cleanup --all

init

Inspect system prerequisites (Node.js runtime, Git version, storage paths, GitHub API authentication status, rate limits).

npx gsoc-contrib init

Workspace Context Files (.contrib/ISSUE.md & .contrib/AI_PROMPT.md)

When a contribution workspace is initialized, gsoc-contrib automatically generates:

1. .contrib/ISSUE.md: Complete issue briefing with title, description, state, labels, candidate files, and test commands.
2. .contrib/AI_PROMPT.md (v2 Context Engine): Surgical instructions for AI coding assistants (Antigravity, Cursor, Copilot, Claude Code) with:
   • Extracted testing and style guidelines from repository CONTRIBUTING.md or DEVELOPMENT.md.
   • Quality checks from detected linters & formatters (ESLint, Prettier, Biome, Ruff, Black, Mypy, Clippy, rustfmt, golangci-lint).
   • Pull Request checklist extracted from .github/PULL_REQUEST_TEMPLATE.md.
   • Explicit verification commands and surgical coding rules.
3. .contrib/context.json: Machine-readable metadata for IDE extensions, scripts, and automations.

The .contrib/ folder is automatically excluded in .git/info/exclude so your git working tree stays clean!

Storage Directory Structure

Workspaces, cache, and registry are organized under ~/.contrib:

~/.contrib/
├── registry.json     # Workspace registry tracking active sessions
├── identities.json   # Configured Git and SSH user profiles
├── cache/
│   ├── api/          # Offline & rate-limit cached GitHub API responses
│   └── git/          # Shared bare repositories for instant git worktrees
└── workspaces/       # Isolated contribution workspaces
    ├── psf__requests__issue_6000/
    │   ├── .contrib/ISSUE.md
    │   └── ...
    └── facebook__react__issue_24000/

Architecture

1. Blobless Git Clone (--filter=blob:none): Instead of downloading the entire commit history and all file contents, blobless cloning downloads only commit and tree objects. Git fetches specific file contents on-demand only when files are opened or edited.
2. Local Workspace Registry: Workspaces are tracked centrally in ~/.contrib/registry.json. If you revisit an issue, contrib checks out the existing workspace instead of re-downloading.
3. Strict Safety Sandboxing: The cleanup command verifies that the target directory is strictly located inside the managed workspaces directory before deletion, preventing accidental or malicious file removal.
4. Smart Offline Engine: Caches GitHub API metadata and git bare repositories indefinitely, allowing developers to create workspaces, context files, and branches completely off-grid.
5. Git Identity Isolation: Isolates contributor names, emails, and SSH host configurations locally per workspace, avoiding corporate credential contamination.

Privacy & Security

gsoc-contrib (contrib) is built with a strict privacy-first, local-first architecture. It is designed specifically for open-source developers who value control over their local environment, source code, and credentials.

Data the CLI Application Collects and Stores

The CLI application persists minimal operational data strictly on your local filesystem under ~/.contrib (or the directory specified by $CONTRIB_HOME):

1. Workspace Registry (registry.json): Stores identifiers of active workspaces (id, local filesystem path, GitHub repository owner/repo, issue/PR number, branch name, creation timestamp, and applied identity ID).
2. GitHub API Cache (cache/api/): Caches public issue and pull request metadata (title, body description, labels, and issue author login) to reduce network round-trips, respect rate limits, and support offline workspace creation.
3. Bare Git Cache (cache/git/): Maintains local bare Git mirrors for blobless and worktree clones, saving local disk and bandwidth across multiple issues in the same repository.
4. Git Identities (identities.json, optional): If you configure Git identities via contrib identity add, user-provided author details (name, email, local path to SSH key, and GPG signing key) are stored locally solely to configure Git's local user.name, user.email, commit.gpgsign, or core.sshCommand in your workspaces.

Data the CLI Application Does NOT Collect

The CLI application itself:

• Does NOT collect, store, or transmit IP addresses, personal information, or environment variables (beyond reading documented variables such as GITHUB_TOKEN, GH_TOKEN, CONTRIB_HOME, EDITOR, VISUAL, NO_COLOR, and FORCE_COLOR in memory).
• Does NOT include telemetry, analytics, tracking, fingerprinting, crash reporting (e.g., Sentry, Bugsnag), or external data beacons.
• Does NOT store GitHub authentication tokens, SSH private keys, or passwords on disk. GitHub tokens are held only in process memory for the lifecycle of the command and sent strictly in HTTPS request headers directly to GitHub's official REST API.
• Does NOT inspect or read private SSH key files. If an identity specifies --ssh-key, only the file path is configured into Git's core.sshCommand (ssh -i "<path>").
• Does NOT send repository contents, workspace files, diffs, or credentials to any project-controlled server or third party.
• Does NOT operate any project-controlled backend, analytics database, or remote server.
• Does NOT print or log authentication credentials. Terminal logs, diagnostic outputs (init, doctor), and error traces are filtered through automated credential redaction (redactSensitiveOutput) to scrub tokens and basic authentication strings.

Note on Network Infrastructure Metadata: While the CLI application itself does not collect, record, or transmit user IP addresses or tracking telemetry, standard TCP/IP network transport packets are transmitted by your operating system when communicating with GitHub's servers (e.g., HTTPS requests to api.github.com or Git SSH traffic to github.com). These network-layer interactions are handled by GitHub in accordance with the GitHub Privacy Statement.

Network Request Audit

Every network request initiated by contrib is strictly directed to official GitHub infrastructure or user-specified Git remotes. Below is the comprehensive audit of all network requests in the project and why each one exists:

| Request / Operation | Protocol & Destination | Purpose & Rationale | | :--- | :--- | :--- | | Fetch Issue Metadata | GET https://api.github.com/repos/{owner}/{repo}/issues/{issue} | Retrieves public issue title, description body, labels, and author to populate workspace context (.contrib/ISSUE.md), determine relevant source files, and configure workspace branches. | | Inspect Current User | GET https://api.github.com/user | Determines the authenticated GitHub username to check whether the contributor already owns a fork of the repository. | | Check Existing Fork | GET https://api.github.com/repos/{username}/{repo} | Checks whether a fork exists under the user's account to automatically configure upstream and origin remotes. | | Create Repository Fork | POST https://api.github.com/repos/{owner}/{repo}/forks | Creates a user fork on GitHub when --fork is passed or when preparing PR submission. | | Search Contribution Issues | GET https://api.github.com/search/issues?q=... | Powers the contrib search and contrib browse commands to search public GitHub issues by label, repository, and keywords. | | Check Rate Limits & Auth | GET https://api.github.com/rate_limit | Powers contrib init and contrib doctor to report remaining GitHub API requests and authentication status. | | Get Default Branch | GET https://api.github.com/repos/{owner}/{repo} | Retrieves the repository default branch (main vs master) to properly target base branch checkouts. | | Git Clone / Fetch / Push | Git over HTTPS/SSH to github.com | Standard Git version control operations executed via your system's git executable to clone blobless trees, fetch upstream commits, and push user-committed branches to their fork. |

No network requests are ever made to any other host, service, or project-controlled endpoint.

Dependency Tree & Security Audit

Before every release, the project dependency tree is audited to prevent dependency bloat, typosquatting, or supply chain vulnerabilities:

• Production Dependencies: Only commander (^13.1.0), which has 0 transitive dependencies.
• Security Audit: Verified using npm audit with 0 vulnerabilities.

Development

# Clone the repository
git clone https://github.com/anandmahadevv/contrib-cli.git
cd contrib-cli

# Install dependencies
npm install

# Run test suite (Node.js native test runner)
npm test

# Run CLI locally
node ./bin/cli.js --help

Publishing to npm

To publish a new version:

# 1. Verify tests and dry-run packaging
npm test
npm pack --dry-run

# 2. Login to npm
npm login

# 3. Publish public package
npm publish --access public

License

This project is licensed under the MIT License.