oss-autopilot

You have 12 open PRs across GitHub. A maintainer asked a question 5 days ago. Two PRs have failing CI you haven't noticed. And you're about to open another one.

Sound familiar?

OSS Autopilot is an AI copilot that tracks all your open source PRs, alerts you when something needs attention, and helps you respond to maintainer feedback so your contributions actually get merged.

Quick Start

/plugin marketplace add costajohnt/oss-autopilot
/plugin install oss-autopilot@oss-autopilot

Restart Claude Code, run /oss. Full install guide →

Install

Claude Code Plugin (recommended)

Prerequisites: Claude Code, Node.js 20+, GitHub CLI (gh auth login)

/plugin marketplace add costajohnt/oss-autopilot
/plugin install oss-autopilot@oss-autopilot

Restart Claude Code, then run /setup-oss. Done.

The plugin includes a built-in pre-commit-reviewer agent that reviews all code changes before committing. For enhanced parallel review, install the pr-review-toolkit plugin (search for it in the Claude Code plugin marketplace) — it adds 5 specialized reviewers that run simultaneously:

Without pr-review-toolkit: The built-in pre-commit-reviewer handles all review phases as a single agent with the same fix-and-re-review loop. Everything works — you get one generalist reviewer instead of five specialists.

First initialize your GitHub username (one-time setup):

npx @oss-autopilot/core@latest init <your-github-username>

Then add to your MCP client config:

{
  "mcpServers": {
    "oss-autopilot": {
      "command": "npx",
      "args": ["@oss-autopilot/mcp@latest"]
    }
  }
}

The MCP server exposes 20 tools, 5 resources, and 3 prompts — the full OSS Autopilot feature set.

# Run any command directly (uses gh auth token automatically)
npx @oss-autopilot/core daily --json
npx @oss-autopilot/core dashboard serve

# Or install globally
npm install -g @oss-autopilot/core

# Or import programmatically
npm install @oss-autopilot/core

import { runDaily, runSearch, runStatus } from '@oss-autopilot/core/commands';

const digest = await runDaily();
const issues = await runSearch({ maxResults: 10 });

All commands return { success, data, error, timestamp } with --json.

What It Does

PR Monitoring

Claude checks every open PR you have across all of GitHub and tells you what needs your attention:

15 Active PRs | 2 need attention | Dashboard opened in browser

2 PRs Need Attention (in priority order):

1. [Needs Response] vadimdemedes/ink#855 - Add kitty keyboard support (3d)
   maintainer: tests requested
   Effort: Medium - respond + add tests

2. [CI Failing] rubyforgood/human-essentials#5492 - Add item filter (1d)
   Failing: rspec, lint
   Effort: Medium - investigate CI logs

What would you like to do?
  > Work through all 2 issues (Recommended)
  > Search for new issues
  > Done for now

Then Claude walks you through each issue: drafting responses, diagnosing CI failures, resolving conflicts, until everything is handled.

Issue Discovery

Select "Search for new issues" and the issue scout finds opportunities matched to your history — not just random "good first issue" results:

Found 8 candidates across 6 repos

From repos where you've merged PRs
-
1. expressjs/express#6012 — Add timeout option to res.download()
   Labels: feature, good first issue
   Score: 92/100 — You merged 2 PRs here, clear requirements, active repo
   unclaimed · no linked PRs · last commit 2 days ago

2. chalk/chalk#642 — Support NO_COLOR in browser builds
   Labels: enhancement
   Score: 85/100 — You merged 1 PR here, repo has 7-day merge time
   unclaimed · no linked PRs · CONTRIBUTING.md found

From your starred repos
-
3. sindresorhus/execa#831 — Add encoding option to execaNode
   Labels: good first issue, help wanted
   Score: 78/100 — High-quality repo, clear requirements, recent activity
   unclaimed · no linked PRs · last commit 5 days ago

Skipped (not worth your time)
-
fake-oss/calculator — Label farming detected (6 beginner labels)
inactive/legacy-app — No commits in 90+ days
contested/router#44 — Already claimed by @other-dev 2 days ago

Each issue gets a viability score (0-100) based on your relationship with the repo, issue clarity, project health, and whether someone else has already claimed it. Repos where your PRs got merged are prioritized first — that's where you have the highest chance of getting another PR accepted.

Interactive Dashboard

The dashboard auto-opens at http://localhost:3000 when you run /oss. It's a Preact SPA you can also launch standalone with npx @oss-autopilot/core dashboard serve.

At a glance:

• Stats bar with active, shelved, merged, and closed PR counts plus merge rate

• Status doughnut, repository breakdown, and contribution timeline charts

• Filter and search across all PRs

Manage your PRs:

• PRs are grouped into Need Attention, Waiting on Others, and Shelved sections

• Click any PR for a detail panel showing CI status, failing check classification, review decision, maintainer comments, and checklist progress

• Shelve/Unshelve — temporarily hide PRs you're not actively working on

• Move to Waiting / Move to Need Attention — override the auto-detected status when you know better

All actions persist to ~/.oss-autopilot/state.json.

Putting It Together

A typical contribution lifecycle:

Day 1 — Find and build. Search for issues, pick a high-scoring one from a repo where you've merged before. Implement the fix, run the review-fix convergence loop (lint, test, review agents, fix, repeat until clean), and open a draft PR that references the issue. The PR itself is the claim — no need to comment "I'm working on this" first.

Day 2 — Respond. /oss shows the maintainer requested changes 12 hours ago. The PR responder reads the feedback, fetches code context, and — if the diff addresses it — skips the comment (code speaks for itself). If the maintainer asked a question, it drafts a reply with every claim verified against the actual diff.

Day 5 — Merged. Your repo relationship score improves, and better-matched issues surface next time you search.

Key Capabilities

• Monitors all your PRs — comments, CI failures, merge conflicts, incomplete checklists, maintainer requests

• Excludes private repos — filters out private repos and orgs so you only see OSS contributions

• Drafts responses — reads maintainer feedback and writes a reply for your review, with every claim verified against the actual diff

• Smart comment decisions — defaults to skipping comments when the code speaks for itself; only drafts when it adds info the diff can't convey

• Finds issues matched to you — prioritizes repos where you've merged PRs, scores every issue 0-100

• Work-first approach — implements before claiming; the PR is the claim, no unnecessary "I'm working on this" comments

• Review-fix convergence loop — mandatory lint, test, and review cycle before any PR is declared ready

• Scores repositories — evaluates merge rate, review speed, maintainer responsiveness

• Interactive dashboard — manage PRs visually, shelve/unshelve, override statuses, track stats over time

• Optional automation — headless cron jobs for daily PR status, dependabot triage, issue curation, and weekly audits

• Never acts without you — nothing is posted to GitHub without your explicit approval

Usage

Daily Workflow (5 min)

1. Run /oss to see what needs attention

2. Work through critical issues (CI failures, maintainer comments, conflicts)

3. Done for now

Responding to Feedback (10 min)

1. Run /oss to see PRs with new comments

2. Select a PR that needs a response

3. Claude reads the feedback and drafts a response for your review

4. Post it after reviewing

Commands: /oss (daily check), /oss-search (find issues), /setup-oss (configure), /setup-automation (cron jobs), /oss-help (reference)

Specialized Agents

Claude automatically dispatches these based on context:

Agents are available in the Claude Code plugin. MCP and CLI users access the same capabilities through tools and commands.

Headless Automation (Optional)

Set up optional cron jobs that run Claude headlessly to pre-compute results before your sessions. Run /setup-automation for a guided wizard, or configure manually:

The SessionStart hook automatically surfaces the daily report when you start a session, giving Claude instant PR context without the "check my PRs" warmup.

All automations are fully optional — the tool works identically without them.

Contribution Stats & Badges

View Your Stats

oss-autopilot stats              # Terminal output
oss-autopilot stats --json       # Structured JSON
oss-autopilot stats --markdown   # Shareable markdown report
oss-autopilot stats --badge      # Shields.io endpoint JSON

Add a Badge to Your GitHub Profile

Show off your open source contributions with a live badge on your GitHub profile README:

![OSS Contributions](https://img.shields.io/endpoint?url=https://oss-autopilot-stats.vercel.app/api/badge/YOUR_USERNAME)

The badge updates hourly and shows your merge rate, total merged PRs, and active PR count. Only counts PRs to external repos (excludes your own) with 50+ stars by default.

Customize the minimum star threshold with ?minStars=100 (URL-encode the inner URL):

![OSS Contributions](https://img.shields.io/endpoint?url=https%3A%2F%2Foss-autopilot-stats.vercel.app%2Fapi%2Fbadge%2FYOUR_USERNAME%3FminStars%3D100)

Profile Widgets

Embed live SVG widgets in your GitHub profile README for a richer contribution showcase. All widgets update hourly and support ?theme=dark.

Stats Card — merged count, merge rate, repo count, streak:

[![OSS Contributions](https://oss-autopilot-stats.vercel.app/api/card/YOUR_USERNAME)](https://github.com/costajohnt/oss-autopilot)

Recent Contributions — your five most recently merged PRs:

![Recent](https://oss-autopilot-stats.vercel.app/api/recent/YOUR_USERNAME)

Activity Graph — 26-week contribution heatmap:

![Activity](https://oss-autopilot-stats.vercel.app/api/activity/YOUR_USERNAME)

Add ?theme=dark to any URL for a dark background to match dark-mode profiles.

Configuration

Configuration is stored in ~/.oss-autopilot/state.json (inside the config field). Run /setup-oss to configure interactively, or use setup --set key=value from the CLI:

PR tracking state, shelved PRs, dismissed issues, and event history are also stored in ~/.oss-autopilot/state.json.

Curated Issue List

You can maintain a markdown file of pre-researched issues. Set the path during /setup-oss or via setup --set issueListPath=PATH. The parser recognizes:

• GitHub URLs in list items (issues or PRs)

• Section headings (#, ##, ###) as tier labels

• Checkboxes ([x]), strikethrough (~~text~~), or the word Done to mark completed items

Example file:

## Pursue (High Priority)
- https://github.com/facebook/react/issues/12345 — Fix useEffect cleanup order
- https://github.com/vercel/next.js/issues/67890 — Add streaming support for app router

## Maybe (Worth Investigating)
- https://github.com/expressjs/express/issues/111 — Update error handling docs

## Completed
- [x] https://github.com/nodejs/node/issues/222 — Fix stream backpressure (Done)
- ~~https://github.com/vitejs/vite/issues/333 — HMR race condition~~

The /oss-search command can add vetted issues to this file automatically.

How It Works

OSS Autopilot is a pnpm monorepo with four packages, plus a plugin layer:

┌──────────────────────────────────────────────────┐
│  Claude Code Plugin Layer                        │
│  /oss, /oss-search, /setup-oss, /oss-help        │
│  7 specialized agents, contribution skills       │
├──────────────────────────────────────────────────┤
│                                                  │
│  ┌──────────────┐  ┌──────────────────────────┐  │
│  │ MCP Server   │  │ Interactive Dashboard     │  │
│  │ @oss-auto-   │  │ @oss-autopilot/dashboard │  │
│  │ pilot/mcp    │  │ Preact + Vite             │  │
│  │              │  │ PR management, charts,    │  │
│  │ 20 tools     │  │ actions                   │  │
│  │ 5 resources  │  │                           │  │
│  │ 3 prompts    │  │                           │  │
│  └──────┬───────┘  └────────────┬─────────────┘  │
│         │                       │                │
│  ┌──────┴───────────────────────┴─────────────┐  │
│  │ Core Library — @oss-autopilot/core         │  │
│  │ PR monitoring, issue discovery, state mgmt │  │
│  │ GitHub API, CLI, structured JSON output    │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  ┌────────────────────────────────────────────┐  │
│  │ Badge Endpoint — @oss-autopilot/badge-     │  │
│  │ endpoint — Vercel serverless Shields.io    │  │
│  │ badge API (standalone, uses Octokit)       │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
└──────────────────────────────────────────────────┘

MCP Server

The MCP server exposes core CLI commands as MCP tools, making OSS Autopilot available to any MCP-compatible client:

Supports both stdio (default) and HTTP/SSE (--http --port 3001) transports.

Updating

Plugin:

/plugin update oss-autopilot

MCP server / CLI: Uses npx @latest by default, so you always get the latest version. Or pin a version in your config.

Your configuration is preserved across updates. See the Changelog for what's new.

Development

git clone https://github.com/costajohnt/oss-autopilot.git
cd oss-autopilot
pnpm install                 # Install all workspace dependencies
pnpm test                    # Run all tests across all packages
pnpm start -- daily --json   # Run CLI via tsx (no bundle needed)
pnpm run bundle              # Rebuild CLI bundle (esbuild)

Project Structure

├── commands/                    # Plugin slash commands (/oss, /oss-search, /setup-oss, /setup-automation, /oss-help)
├── agents/                      # 7 specialized agents (PR responder, issue scout, etc.)
├── skills/                      # Contribution best practices
├── workflows/                   # Delegated logic loaded by commands on demand
├── hooks/                       # Plugin hooks (session-start)
├── packages/
│   ├── core/                    # @oss-autopilot/core — CLI + core library
│   │   ├── src/commands/        # CLI subcommands
│   │   ├── src/core/            # Domain logic + tests
│   │   └── dist/cli.bundle.cjs  # Built bundle (auto-generated)
│   ├── mcp-server/              # @oss-autopilot/mcp — MCP server
│   │   └── src/                 # Tools, resources, prompts, server
│   ├── dashboard/               # @oss-autopilot/dashboard — Interactive UI
│   └── badge-endpoint/          # @oss-autopilot/badge-endpoint — Vercel badge API
└── pnpm-workspace.yaml          # Workspace definition

Test as a local plugin:

claude --plugin-dir ./oss-autopilot

Git hooks (via simple-git-hooks):

Claude Code hooks (.claude/hooks/, PreToolUse on Bash):

FAQ & Troubleshooting

Does Claude post comments or push code automatically? No. Claude drafts responses and suggests actions. Nothing is posted to GitHub without your explicit approval.

Where is my data stored? All data lives in ~/.oss-autopilot/ — configuration, PR tracking state, event history, and HTTP cache. The dashboard runs locally at http://localhost:3000. Nothing is sent to external servers beyond GitHub API calls to fetch your PR data.

Does it work with private repos? Yes, as long as your GitHub CLI (gh) has access.

Can I use this without Claude Code? Yes. The MCP server (npx @oss-autopilot/mcp) works with Cursor, Claude Desktop, Codex, Windsurf, and any MCP client. The CLI (npx @oss-autopilot/core daily --json) runs standalone. The npm package (@oss-autopilot/core) can be imported programmatically. The Claude Code plugin provides the best experience with specialized agents and skills, but all core functionality is available through any path.

Any tips for getting started? Set maxActivePRs to 3-5 when starting out. Fewer active PRs with fast responses beats many stale ones. Run /oss every few days — stale PRs are hard to revive.

GitLab / Gitea / Bitbucket support? Not yet — see Limitations below.

Error: gh: command not found

Install GitHub CLI and authenticate:

brew install gh    # macOS
gh auth login

The CLI bundles automatically on first use. If it fails:

# Find your plugin directory
find ~/.claude/plugins -name "oss-autopilot" -type d

# Rebuild
cd <path-from-find-command>/packages/core
npm install
npm run bundle

The interactive dashboard runs at http://localhost:3000. If it doesn't open automatically, try launching it manually with npx @oss-autopilot/core dashboard serve, then open http://localhost:3000 in your browser.

• Run /setup-oss to ensure your GitHub username is configured

• Check that gh auth status shows you're authenticated

• The plugin only tracks PRs you authored

Limitations

• GitHub only — GitLab, Bitbucket, and other forges are not supported. Contributions welcome.

• 1,000 PR cap — GitHub's Search API returns at most 1,000 results per query. If you have more than 1,000 open, merged, or closed PRs, the oldest results from each search may be truncated.

• Rate limiting — The CLI automatically backs off on GitHub rate limits (with up to 2 retries) and secondary rate limits (1 retry), but sustained heavy use can exhaust these retries. If this happens, wait a few minutes and retry.

• Individual contributor focus — Designed for solo contributors managing their own PRs. No team dashboards, shared state, or multi-user workflows.

API Documentation

Full API documentation for @oss-autopilot/core is available at jcosta.tech/oss-autopilot.

Contributing

Bug fixes, new agents, CLI improvements, and documentation are all welcome. See CONTRIBUTING.md for setup instructions.

License

MIT