{"id":47701670,"url":"https://github.com/costajohnt/oss-scout","last_synced_at":"2026-05-19T01:04:32.396Z","repository":{"id":347470111,"uuid":"1194109022","full_name":"costajohnt/oss-scout","owner":"costajohnt","description":"Find open source issues personalized to your contribution history. Three-strategy search, deep vetting, and viability scoring.","archived":false,"fork":false,"pushed_at":"2026-05-09T05:04:33.000Z","size":642,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T06:35:34.926Z","etag":null,"topics":["claude-code-plugin","cli","contribution-finder","contributions","github","github-api","issue-discovery","issue-vetting","mcp","npx","open-source","personalized","typescript","vetting"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@oss-scout/core","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/costajohnt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-27T23:43:05.000Z","updated_at":"2026-05-09T04:36:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"e9eeeb48-fa07-40fd-aac6-2b2d8ccf3487","html_url":"https://github.com/costajohnt/oss-scout","commit_stats":null,"previous_names":["costajohnt/oss-scout"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/costajohnt/oss-scout","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costajohnt%2Foss-scout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costajohnt%2Foss-scout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costajohnt%2Foss-scout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costajohnt%2Foss-scout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/costajohnt","download_url":"https://codeload.github.com/costajohnt/oss-scout/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/costajohnt%2Foss-scout/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33196091,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code-plugin","cli","contribution-finder","contributions","github","github-api","issue-discovery","issue-vetting","mcp","npx","open-source","personalized","typescript","vetting"],"created_at":"2026-04-02T17:21:46.576Z","updated_at":"2026-05-19T01:04:32.337Z","avatar_url":"https://github.com/costajohnt.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icon.svg\" alt=\"oss-scout\" width=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eoss-scout\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Find open source issues personalized to \u003cem\u003eyour\u003c/em\u003e contribution history\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@oss-scout/core\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/@oss-scout/core\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/npm/dm/@oss-scout/core\" alt=\"downloads\"\u003e\n  \u003cimg src=\"https://github.com/costajohnt/oss-scout/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20-brightgreen\" alt=\"Node 20+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Claude_Code-Plugin-blueviolet\" alt=\"Claude Code Plugin\"\u003e\n\u003c/p\u003e\n\nMost issue finders search GitHub for `good first issue` labels and hand you a list. You could do that yourself in 30 seconds.\n\n**oss-scout is different.** It knows which repos you've contributed to, which maintainers have merged your work before, and which projects are actually responsive. It searches strategically, vets every result, and tells you where your next PR has the highest chance of getting merged.\n\n## Getting Started\n\n### Prerequisites\n\n- **Node.js 20+**\n- **GitHub CLI** — `gh auth login` ([install](https://cli.github.com/)) or set `GITHUB_TOKEN` env var\n\n### Install\n\n```bash\nnpx @oss-scout/core setup    # configure (no install needed)\nnpx @oss-scout/core search   # find issues\n```\n\nOr install globally: `npm install -g @oss-scout/core`\n\n### First run\n\n**1. Configure your preferences:**\n\n```\n$ oss-scout setup\n\n🔧 oss-scout setup\n\nDetecting GitHub username...\nGitHub username [yourname]:\nPreferred languages (or \"any\" for all) [any]: typescript, rust\nIssue labels to search for [good first issue, help wanted]:\nDifficulty scope (beginner, intermediate, advanced) [all]: beginner, intermediate\nMinimum repo stars [50]: 100\nProject categories (nonprofit, devtools, infrastructure, web-frameworks, data-ml, education) [none]: devtools\nRepos to exclude (owner/repo, comma-separated, optional):\n\n✅ Setup complete! Preferences saved.\n```\n\n**2. Import your GitHub history** (so the tool knows where you've contributed before):\n\n```\n$ oss-scout bootstrap\n\nImported 23 merged PRs, 4 closed PRs, 142 starred repos\nScored 8 repositories\n```\n\n**3. Search for issues:**\n\n```\n$ oss-scout search\n\nFound 8 issue candidates:\n\n  ✅ owner/repo#123 [92/100]\n     Add timeout option to res.download()\n     https://github.com/owner/repo/issues/123\n     Repo: 9/10, 2 merged PRs\n\n  ✅ org/project#456 [85/100]\n     Support NO_COLOR in browser builds\n     https://github.com/org/project/issues/456\n     Repo: 8/10, 1 merged PRs\n\n  ⚠️ user/library#789 [78/100]\n     Add encoding option to execaNode\n     https://github.com/user/library/issues/789\n```\n\nResults are automatically saved. View them later with `oss-scout results`.\n\n## How Search Works\n\noss-scout runs four search strategies in priority order:\n\n| Strategy | Flag | What it searches | Why it matters |\n|----------|------|-----------------|----------------|\n| `merged` | Phase 0 | Repos where you have merged PRs | Highest merge probability |\n| `starred` | Phase 1 | Your GitHub starred repos | Implicit interest |\n| `broad` | Phase 2 | General label/language filtered | Discovery |\n| `maintained` | Phase 3 | Actively maintained repos by topic | Exploration |\n\nRun all strategies (default), or pick specific ones:\n\n```bash\noss-scout search --strategy merged           # only repos you've contributed to\noss-scout search --strategy starred,broad     # starred repos + general discovery\noss-scout search --strategy all               # all strategies (default)\n```\n\nHeavy strategies (broad, maintained) are automatically skipped when your GitHub API quota is low.\n\n## Why Not Just Search GitHub?\n\n| Feature | Label search | oss-scout |\n|---------|-------------|-----------|\n| Personalized to your history | No | Yes — prioritizes repos you've contributed to |\n| Checks if issue is claimed | No | Yes — scans comments for claim phrases |\n| Checks for existing PRs | No | Yes — uses timeline API |\n| Project health check | No | Yes — commit recency, stars, CONTRIBUTING.md |\n| Viability scoring | No | Yes — 0-100 with transparent factors |\n| Rate limit aware | No | Yes — adaptive budget, never wastes quota |\n| Spam detection | No | Yes — filters label farming, templated titles |\n\n## Vetting\n\nEvery issue candidate goes through 6 parallel checks:\n\n| Check | What it detects | Method |\n|-------|----------------|--------|\n| Existing PRs | Someone already submitted a fix | Timeline API |\n| Claimed | \"I'm working on this\" in comments | Comment text scanning |\n| Project health | Is the repo active and maintained? | Commit history, stars, forks |\n| Clear requirements | Can you actually implement this? | Body analysis (steps, code blocks) |\n| Contribution guidelines | Branch naming, test framework, CLA | CONTRIBUTING.md probing |\n| Your merge history | Have your PRs been merged here before? | Search API (cached) |\n\n**Vet a specific issue:**\n\n```\n$ oss-scout vet https://github.com/owner/repo/issues/123\n\n✅ owner/repo#123: APPROVE\n   Add timeout option to res.download()\n\nReasons to approve:\n  + Trusted project (2 PRs merged)\n  + Clear requirements\n  + Contribution guidelines found\n\nProject health: Active\n  Last commit: 2 days ago\n```\n\n**Re-vet all saved results** to check for staleness:\n\n```\n$ oss-scout vet-list --prune\n\n  ✅ owner/repo#123 — still_available [92/100]\n  🔒 user/library#789 — claimed [78/100]\n  🔀 org/project#456 — has_pr [85/100]\n\nSummary: 5 available, 1 claimed, 1 has PR, 1 closed\nPruned 3 unavailable issues from saved results.\n```\n\n## Saved Results\n\nSearch 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.\n\n```bash\noss-scout results             # view saved results\noss-scout results --json      # structured JSON output\noss-scout results clear       # wipe saved results\noss-scout vet-list --prune    # re-vet and remove stale issues\n```\n\n### Skip list\n\nSkip issues you don't want to see again. Skipped issues are excluded from future search results and auto-expire after 90 days.\n\n```bash\noss-scout skip add https://github.com/owner/repo/issues/123    # skip an issue\noss-scout skip list                                              # show skipped issues\noss-scout skip remove https://github.com/owner/repo/issues/123  # unskip\noss-scout skip clear                                             # clear all skips\n```\n\nSkipping 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.\n\n### Cross-machine sync with gist persistence\n\nEnable gist persistence to sync your state (preferences, repo scores, PR history, saved results) across machines via a private GitHub gist:\n\n```bash\noss-scout config set persistence gist\n```\n\nYour GitHub token needs the `gist` scope: `gh auth refresh -s gist`\n\nState 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.\n\n## Configuration\n\n### Interactive setup\n\n```bash\noss-scout setup    # first-run interactive configuration\n```\n\n### View and update individual settings\n\n```bash\noss-scout config                                    # show all preferences\noss-scout config --json                             # JSON output\noss-scout config set languages \"typescript,rust\"    # set languages\noss-scout config set minStars 100                   # minimum repo stars\noss-scout config set includeDocIssues false          # exclude doc-only issues\noss-scout config set excludeRepos \"+spam/repo\"       # append to exclude list\noss-scout config set excludeRepos \"-spam/repo\"       # remove from exclude list\noss-scout config reset                               # reset to defaults\n```\n\n### All configuration options\n\n| Key | Type | Default | Description |\n|-----|------|---------|-------------|\n| `languages` | string[] | any (all languages) | Programming language filter (use \"any\" for no filter) |\n| `labels` | string[] | good first issue, help wanted | Issue label filter |\n| `scope` | enum[] | all | Difficulty: beginner, intermediate, advanced |\n| `minStars` | number | 50 | Minimum repo star count |\n| `maxIssueAgeDays` | number | 90 | Skip issues older than this |\n| `includeDocIssues` | boolean | true | Include documentation-only issues |\n| `minRepoScoreThreshold` | number | 4 | Skip repos scoring below this (1-10) |\n| `excludeRepos` | string[] | [] | Repos to never search |\n| `aiPolicyBlocklist` | string[] | matplotlib/matplotlib | Repos with anti-AI policies |\n| `projectCategories` | enum[] | [] | Topic filter: devtools, web-frameworks, etc. |\n| `persistence` | enum | local | State storage: local or gist |\n\n## Install Options\n\n### CLI (recommended for individual use)\n\n```bash\nnpm install -g @oss-scout/core\noss-scout setup\noss-scout bootstrap\noss-scout search\n```\n\n### Claude Code Plugin\n\n```\n/plugin marketplace add costajohnt/oss-scout\n/plugin install oss-scout@oss-scout\n```\n\nRestart Claude Code. Commands:\n- `/scout` — Multi-strategy issue search with interactive results\n- `/scout-setup` — Configure preferences\n\nAgents (dispatched automatically by Claude):\n- **issue-scout** — Autonomous issue discovery and vetting\n- **repo-evaluator** — Repository health assessment before contributing\n\n### MCP Server (Cursor, Claude Desktop, Codex, Windsurf)\n\n```json\n{\n  \"mcpServers\": {\n    \"oss-scout\": {\n      \"command\": \"npx\",\n      \"args\": [\"@oss-scout/mcp@latest\"]\n    }\n  }\n}\n```\n\n**Tools:** search, vet, skip, config, config-set\n**Resources:** scout://config, scout://results, scout://scores\n\n### As a Library\n\n```bash\nnpm install @oss-scout/core\n```\n\n```typescript\nimport { createScout } from '@oss-scout/core';\n\nconst scout = await createScout({ githubToken: process.env.GITHUB_TOKEN });\nconst results = await scout.search({ maxResults: 10 });\n\nfor (const c of results.candidates) {\n  console.log(`${c.issue.repo}#${c.issue.number}: ${c.viabilityScore}/100`);\n}\n```\n\nTwo persistence modes:\n- **`'provided'`** — caller manages state (for embedding in other tools)\n- **`'gist'`** — oss-scout manages state via private GitHub gist\n\n```typescript\n// Host application provides state\nconst scout = await createScout({\n  githubToken: token,\n  persistence: 'provided',\n  initialState: existingState,\n});\n\n// Record PR outcomes to improve future search quality\nscout.recordMergedPR({ url, title, mergedAt, repo });\nscout.recordClosedPR({ url, title, closedAt, repo });\nawait scout.checkpoint(); // push to gist\n```\n\n## Viability Scoring (0-100)\n\n| Factor | Points | Condition |\n|--------|--------|-----------|\n| Base | 50 | Always |\n| Repo score | +0 to +20 | From 1-10 repo quality rating |\n| Repo quality bonus | +0 to +12 | Stars and forks tiers |\n| Merged PRs in repo | +15 | You've had PRs merged here |\n| Clear requirements | +15 | Issue body has steps, code blocks, keywords |\n| Fresh issue | +0 to +15 | Updated within 14 days (full), 15-30 days (partial) |\n| Contribution guidelines | +10 | CONTRIBUTING.md found and parsed |\n| Org affinity | +5 | Merged PRs in other repos under same org |\n| Category match | +5 | Matches your preferred project categories |\n| Existing PR | -30 | Someone already submitted a fix |\n| Claimed | -20 | Someone commented they're working on it |\n| Closed-without-merge history | -15 | Repo has rejected your PRs before (no merges) |\n\nScore is clamped to 0-100. Results sorted by: search priority \u003e recommendation \u003e score.\n\n## CLI Reference\n\n```\noss-scout [--debug] [--json] \u003ccommand\u003e\n\nSetup:\n  setup                         Interactive first-run configuration\n  bootstrap                     Import starred repos and PR history from GitHub\n\nSearch:\n  search [count]                Search for issues (default: 10)\n    --strategy \u003cs\u003e              Strategies: merged,starred,broad,maintained,all\n  vet \u003cissue-url\u003e               Vet a specific issue\n  vet-list                      Re-vet all saved results\n    --prune                     Remove unavailable issues\n    --concurrency \u003cn\u003e           Max parallel API requests (default: 5)\n\nResults:\n  results                       Show saved search results\n  results clear                 Clear saved results\n\nSkip:\n  skip add \u003cissue-url\u003e          Skip an issue (exclude from searches)\n  skip list                     Show all skipped issues\n  skip remove \u003cissue-url\u003e       Unskip an issue\n  skip clear                    Clear all skipped issues\n\nConfig:\n  config                        Show current preferences\n  config set \u003ckey\u003e \u003cvalue\u003e      Update a preference\n  config reset                  Reset to defaults\n\nGlobal:\n  --debug                       Debug logging\n  --json                        Structured JSON output\n  --version                     Show version\n```\n\n## Spam Detection\n\nAutomatically filtered out:\n- **Label farming** — repos with 5+ beginner labels per issue\n- **Templated titles** — mass-created issues (\"Add Question #42\", \"Add Question #43\")\n- **Anti-AI policies** — repos in the `aiPolicyBlocklist` (configurable)\n\n## Architecture\n\n```\n@oss-scout/core\n├── OssScout class          Public API, implements ScoutStateReader\n├── IssueDiscovery          Multi-phase search orchestrator\n├── IssueVetter             Parallel vetting pipeline\n├── issue-eligibility       PR checks, claim detection, requirements analysis\n├── issue-scoring           Viability scoring (pure functions)\n├── issue-filtering         Spam detection, doc-only filtering, per-repo caps\n├── search-phases           GitHub Search API helpers, caching, batching\n├── search-budget           Rate limit tracking (30 req/min sliding window)\n├── repo-health             Project health checks, CONTRIBUTING.md parsing\n├── category-mapping        Project categories to GitHub topic mapping\n├── http-cache              ETag response caching, in-flight deduplication\n├── gist-state-store        Gist-backed persistence with conflict resolution\n└── ScoutState (Zod)        Preferences, repo scores, PR history, saved results\n```\n\n## License\n\nMIT\n\n## Related\n\n- [OSS Autopilot](https://github.com/costajohnt/oss-autopilot) — full AI copilot for managing open source contributions (uses oss-scout for issue discovery)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcostajohnt%2Foss-scout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcostajohnt%2Foss-scout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcostajohnt%2Foss-scout/lists"}