oss-scout
Find open source issues personalized to your contribution history
Most issue finders search GitHub for good first issue labels and hand you a list. You could do that yourself in 30 seconds.
oss-scout is different. It knows which repos you've contributed to, which maintainers have merged your work before, and which projects are actively maintained. It searches strategically, vets every result, and tells you where your next PR has the highest chance of getting merged.
Getting Started
Prerequisites
- Node.js 20+
- GitHub CLI —
gh auth login(install) or setGITHUB_TOKENenv var
Install
npx @oss-scout/core setup # configure (no install needed)
npx @oss-scout/core search # find issues
Or install globally: npm install -g @oss-scout/core
First run
1. Configure your preferences:
$ oss-scout setup
🔧 oss-scout setup
Detecting GitHub username...
GitHub username [yourname]:
Preferred languages (or "any" for all) [any]: typescript, rust
Issue labels to search for [good first issue, help wanted]:
Difficulty scope (beginner, intermediate, advanced) [all]: beginner, intermediate
Minimum repo stars [50]: 100
Project categories (nonprofit, devtools, infrastructure, web-frameworks, data-ml, education) [none]: devtools
Repos to exclude (owner/repo, comma-separated, optional):
✅ Setup complete! Preferences saved.
2. Import your GitHub history (so the tool knows where you've contributed before):
$ oss-scout bootstrap
Imported 23 merged PRs, 4 closed PRs, 142 starred repos
Scored 8 repositories
3. Search for issues:
$ oss-scout search
Found 8 issue candidates:
✅ owner/repo#123 [92/100]
Add timeout option to res.download()
https://github.com/owner/repo/issues/123
Repo: 9/10, 2 merged PRs
✅ org/project#456 [85/100]
Support NO_COLOR in browser builds
https://github.com/org/project/issues/456
Repo: 8/10, 1 merged PRs
⚠️ user/library#789 [78/100]
Add encoding option to execaNode
https://github.com/user/library/issues/789
Results are automatically saved. View them later with oss-scout results.
How Search Works
oss-scout has five search strategies:
| Strategy | Flag | What it searches | Why it matters |
|---|---|---|---|
merged | Phase 0 | Repos where you have merged PRs | Highest merge probability |
orgs | Orgs phase | Repos in your preferredOrgs | Explicit interest |
starred | Phase 1 | Your GitHub starred repos | Implicit interest |
broad | Phase 2 | General label/language filtered | Discovery |
maintained | Phase 3 | Actively maintained repos by topic | Exploration |
Each search runs one strategy, taking turns across runs (round-robin): the next search runs the next strategy in the table. That keeps a search to one strategy's worth of GitHub API calls while consecutive searches still cover every source. If the strategy whose turn it is finds nothing usable, the search moves on to the next one so it doesn't come back empty. Strategies with nothing to search (no preferredOrgs, no starred repos) are passed over.
--strategy limits which strategies take turns:
oss-scout search --strategy merged # only repos you've contributed to
oss-scout search --strategy starred,broad # alternate between starred repos and general discovery
oss-scout search --strategy all # rotate through all strategies (default)
oss-scout search --full # run every strategy in this one search
The starred strategy is skipped when your GitHub REST search quota is critically low; broad and maintained run on the GraphQL API and aren't affected by it.
Why Not Just Search GitHub?
| Feature | Label search | oss-scout |
|---|---|---|
| Personalized to your history | No | Yes — prioritizes repos you've contributed to |
| Checks if issue is claimed | No | Yes — scans comments for claim phrases |
| Checks for existing PRs | No | Yes — uses timeline API |
| Project health check | No | Yes — commit recency, stars, CONTRIBUTING.md |
| Viability scoring | No | Yes — 0-100 with transparent factors |
| Rate limit aware | No | Yes — adaptive budget, never wastes quota |
| Spam detection | No | Yes — filters label farming, templated titles |
Vetting
Every issue candidate goes through 6 parallel checks:
| Check | What it detects | Method |
|---|---|---|
| Existing PRs | Someone already submitted a fix | Timeline API |
| Claimed | "I'm working on this" in comments | Comment text scanning |
| Project health | Is the repo active and maintained? | Commit history, stars, forks |
| Clear requirements | Can you actually implement this? | Body analysis (steps, code blocks) |
| Contribution guidelines | Branch naming, test framework, CLA | CONTRIBUTING.md probing |
| Your merge history | Have your PRs been merged here before? | Search API (cached) |
Vet a specific issue:
$ oss-scout vet https://github.com/owner/repo/issues/123
✅ owner/repo#123: APPROVE
Add timeout option to res.download()
Reasons to approve:
+ Trusted project (2 PRs merged)
+ Clear requirements
+ Contribution guidelines found
Project health: Active
Last commit: 2 days ago
Re-vet all saved results to check for staleness:
$ oss-scout vet-list --prune
✅ owner/repo#123 — still_available [92/100]
🔒 user/library#789 — claimed [78/100]
🔀 org/project#456 — has_pr [85/100]
🔔 Changes since last check (1):
user/library#789: still_available → claimed
Summary: 5 available, 1 claimed, 1 has PR, 1 closed
Pruned 3 unavailable issues from saved results.
Each run records every saved result's status, so the next vet-list reports just what changed ("was available, now claimed"). The transitions are also in the --json envelope (transitions[]), so a scheduler can act on them without re-diffing.
Saved Results
Search results are automatically saved to ~/.oss-scout/state.json after each search. Results deduplicate across runs — if the same issue appears again, scores are updated but the first-seen date is preserved.
oss-scout results # view saved results
oss-scout results --json # structured JSON output
oss-scout results clear # wipe saved results
oss-scout vet-list --prune # re-vet and remove stale issues
Skip list
Skip issues you don't want to see again. Skipped issues are excluded from future search results permanently; issues the vetter rejects land here too, with the reason.
oss-scout skip add https://github.com/owner/repo/issues/123 # skip an issue
oss-scout skip list # show skipped issues
oss-scout skip remove https://github.com/owner/repo/issues/123 # unskip
oss-scout skip clear # clear all skips
Skipping an issue also removes it from saved results. When you skip an issue that was in your saved results, metadata (repo, title, number) is preserved in the skip entry for context.
Cross-machine sync with gist persistence
Enable gist persistence to sync your state (preferences, repo scores, PR history, saved results) across machines via a private GitHub gist:
oss-scout config set persistence gist
Your GitHub token needs the gist scope: gh auth refresh -s gist
State is automatically pushed to the gist after each search, vet-list, or bootstrap. When you run oss-scout on a different machine, it finds the gist and pulls the latest state.
Configuration
Interactive setup
oss-scout setup # first-run interactive configuration
View and update individual settings
oss-scout config # show all preferences
oss-scout config --json # JSON output
oss-scout config set languages "typescript,rust" # set languages
oss-scout config set minStars 100 # minimum repo stars
oss-scout config set includeDocIssues false # exclude doc-only issues
oss-scout config set excludeRepos "+spam/repo" # append to exclude list
oss-scout config set excludeRepos -- "-spam/repo" # remove ("--" escapes the dash)
oss-scout config reset # reset to defaults
All configuration options
| Key | Type | Default | Description |
|---|---|---|---|
githubUsername | string | (detected) | Your GitHub login; seeds personalization |
languages | string[] | any (all languages) | Programming language filter (use "any" for no filter) |
labels | string[] | good first issue, help wanted | Issue label filter |
scope | enum[] | all | Difficulty: beginner, intermediate, advanced |
minStars | number | 50 | Minimum repo star count |
maxIssueAgeDays | number | 90 | Skip issues older than this |
includeDocIssues | boolean | true | Include documentation-only issues |
minRepoScoreThreshold | number | 4 | Skip repos scoring below this (1-10) |
excludeRepos | string[] | [] | Repos to never search |
excludeOrgs | string[] | [] | Orgs to never search |
preferredOrgs | string[] | [] | Orgs the orgs strategy searches (max 8 per query) |
aiPolicyBlocklist | string[] | matplotlib/matplotlib | Repos with anti-AI policies |
projectCategories | enum[] | [] | Topic filter: devtools, web-frameworks, etc. |
defaultStrategy | enum[] | all | Default search strategies: merged, orgs, starred, broad, maintained |
interPhaseDelayMs | number | 0 | Fixed pause before a search moves on to the next strategy. Off by default: the search budget tracker already paces calls against the 30/min limit |
broadPhaseDelayMs | number | 0 | Extra delay before the broad phase. Not used by since round-robin; applies only to library callers of that run every phase |
Install Options
CLI (recommended for individual use)
npm install -g @oss-scout/core
oss-scout setup
oss-scout bootstrap
oss-scout search
Claude Code Plugin
/plugin marketplace add costajohnt/oss-scout
/plugin install oss-scout@oss-scout
Restart Claude Code. Commands:
/scout— Multi-strategy issue search with interactive results/scout-setup— Configure preferences
Agents (dispatched automatically by Claude):
- issue-scout — Autonomous issue discovery and vetting
- repo-evaluator — Repository health assessment before contributing
MCP Server (Cursor, Claude Desktop, Codex, Windsurf)
{
"mcpServers": {
"oss-scout": {
"command": "npx",
"args": ["-y", "@oss-scout/mcp@latest"]
}
}
}
Tools: search, scout-features, vet, skip, config, config-set, sync Resources: scout://config, scout://results, scout://scores
Scheduled digest (GitHub Action)
Run search on a schedule and open/update a digest issue in your repo with the top candidates. Copy examples/weekly-digest.yml into .github/workflows/ in your own repo:
on:
schedule:
- cron: "0 14 * * 1" # Mondays 14:00 UTC
permissions:
issues: write
jobs:
digest:
runs-on: ubuntu-latest
steps:
- uses: costajohnt/oss-scout@core-v1.9.0 # x-release-please-version
with:
github-username: your-github-login
search-token: ${{ secrets.OSS_SCOUT_TOKEN }} # PAT for personalization (optional)
Inputs: github-username, search-token, issue-token, max-results, strategy, issue-title, issue-label, version. The action reuses the existing CLI (search + results --markdown); no extra machinery.
Pin the action to a release tag (core-vX.Y.Z, as above) or a commit SHA; there is no moving v1 tag. The version input (default latest) separately controls which @oss-scout/core CLI version the action installs and runs.
As a Library
npm install @oss-scout/core
import { createScout } from '@oss-scout/core';
const scout = await createScout({ githubToken: process.env.GITHUB_TOKEN });
const results = await scout.search({ maxResults: 10 });
for (const c of results.candidates) {
console.log(`${c.issue.repo}#${c.issue.number}: ${c.viabilityScore}/100`);
}
Three persistence modes:
'local'(default) — loads and saves~/.oss-scout/state.json'gist'— oss-scout manages state via a private GitHub gist'provided'— caller owns the state object (for embedding in other tools)
// Host application provides and owns the state
const scout = await createScout({
githubToken: token,
persistence: 'provided',
initialState: existingState,
});
// Record PR outcomes to improve future search quality
scout.recordMergedPR({ url, title, mergedAt, repo });
scout.recordClosedPR({ url, title, closedAt, repo });
// checkpoint() persists according to the mode: it writes local state in
// 'local' mode and pushes the gist in 'gist' mode. In 'provided' mode the
// caller owns persistence, so checkpoint() does not write — read scout.getState().
await scout.checkpoint();
Viability Scoring (0-100)
| Factor | Points | Condition |
|---|---|---|
| Base | 50 | Always |
| Repo score | +0 to +20 | From 1-10 repo quality rating |
| Repo quality bonus | +0 to +12 | Stars and forks tiers |
| Merged PRs in repo | +15 | You've had PRs merged here |
| Clear requirements | +15 | Issue body has steps, code blocks, keywords |
| Fresh issue | +0 to +15 | Updated within 14 days (full), 15-30 days (partial) |
| Contribution guidelines | +10 | CONTRIBUTING.md found and parsed |
| Org affinity | +5 | Merged PRs in other repos under same org |
| Category match | +5 | Matches your preferred project categories |
| Existing PR | -30 | Someone already submitted a fix |
| Claimed | -20 | Someone commented they're working on it |
| Closed-without-merge history | -15 | Repo has rejected your PRs before (no merges) |
Score is clamped to 0-100. Results sorted by: search priority > recommendation > score.
CLI Reference
oss-scout [--debug] <command> [--json]
Note: --debug is program-level; --json is a per-subcommand flag (it goes after
the command, e.g. `oss-scout search --json`, not `oss-scout --json search`).
Setup:
setup Interactive first-run configuration
bootstrap Import starred repos and PR history from GitHub
sync Reconcile tracked open PRs (mark merged/closed)
Search:
search [count] Search for issues (default: 10)
--strategy <s> Strategies: merged,orgs,starred,broad,maintained,all
--full Run every strategy this search (not one in rotation)
--prefer-languages <list> Soft-boost ranking for matching repo languages
--prefer-repos <list> Soft-boost ranking for these owner/repo slugs
--avoid-repos <list> Soft-penalize ranking for these owner/repo slugs
--boost-issue-types <list> Soft-boost ranking for matching label types
--diversity-ratio <n> Reserve a fraction (0-1) of slots for unboosted
features [count] Feature opportunities in repos with 3+ merged PRs
--anchor-threshold <n> Override featuresAnchorThreshold (1-50)
--split-ratio <r> Override featuresSplitRatio (0-1)
--broad Search across the ecosystem, not just anchors
vet <issue-url> Vet a specific issue
vet-list Re-vet all saved results
--prune Remove unavailable issues
--concurrency <n> Max parallel API requests (default: 5)
Results:
results Show saved search results
--markdown Render as a markdown table (for digests)
--new-only Only results first seen since the last search
--since <date> Only results first seen at/after this date
results clear Clear saved results
Skip:
skip add <issue-url> Skip an issue (exclude from searches)
skip list Show all skipped issues
skip remove <issue-url> Unskip an issue
skip clear Clear all skipped issues
Config:
config Show current preferences
config set <key> <value> Update a preference
config reset Reset to defaults
Global:
--debug Debug logging
--json Structured JSON output
--version Show version
Spam Detection
Automatically filtered out:
- Label farming — repos with 5+ beginner labels per issue
- Templated titles — mass-created issues ("Add Question #42", "Add Question #43")
- Anti-AI policies — repos in the
aiPolicyBlocklist(configurable)
Architecture
@oss-scout/core
├── OssScout class Public API, implements ScoutStateReader
├── IssueDiscovery Multi-phase search orchestrator
├── IssueVetter Parallel vetting pipeline
├── issue-eligibility PR checks, claim detection, requirements analysis
├── issue-scoring Viability scoring (pure functions)
├── issue-filtering Spam detection, doc-only filtering, per-repo caps
├── anti-llm-policy Detect repos with anti-AI contribution policies
├── feature-discovery `scout features` anchor + broad discovery
├── personalization preferLanguages/preferRepos boosts + diversity
├── linked-pr / roadmap Stalled-PR detection, ROADMAP.md scraping
├── slm-triage Optional local Ollama SLM pre-triage
├── search-phases GitHub Search API helpers, caching, batching
├── search-budget Rate limit tracking (30 req/min sliding window)
├── repo-health Project health checks, CONTRIBUTING.md parsing
├── category-mapping Project categories to GitHub topic mapping
├── http-cache ETag response caching, in-flight deduplication
├── gist-state-store Gist-backed persistence with conflict resolution
└── ScoutState (Zod) Preferences, repo scores, PR history, saved results
License
MIT
Related
- OSS Autopilot — full AI copilot for managing open source contributions (uses oss-scout for issue discovery)