oss-autopilot
It is an MCP server for OSS Autopilot that helps monitor open-source PRs/issues and manage your contribution workflow.
Run daily PR monitoring: fetch open PRs, enrich CI/review/conflict status, and return a prioritized summary.
Show tracking status (open/shelved PRs, dismissed issues), optionally offline from cached state.
Search for beginner-friendly issues and vet candidate issue URLs for contribution suitability.
Track or untrack PRs; shelve/unshelve PRs; dismiss/undismiss issues; mark PR notifications read (one or all); move PRs among attention, waiting, shelved, or auto states.
Fetch PR comments (optionally including bots) and post comments on issues/PRs; claim issues by posting intent comments.
Configure/init/setup OSS Autopilot and run setup/startup checks.
Provides automated triage for Dependabot alerts and pull requests as part of a headless workflow for maintaining open-source repositories.
Monitors GitHub pull requests to track CI failures, merge conflicts, and maintainer feedback, while identifying new open-source contribution opportunities based on the user's history and repository health.
If you contribute to more than a couple of projects, PRs go stale without you noticing. A maintainer asks for a change, CI breaks after a rebase, a branch picks up a conflict, and you find out two weeks later.
OSS Autopilot checks every open PR you have on GitHub and sorts them into what needs you and what is waiting on someone else. For the ones that need you, it helps draft the reply, diagnose the CI failure, or rebase the branch. You approve each push and each comment before it goes out.

Contents
Related MCP server: MCP GitHub Project Manager
Requirements
Node.js 22 or newer
GitHub CLI installed and logged in (
gh auth login), or aGITHUB_TOKENin your environmentFor the plugin: Claude Code, plus
npmand network access on first run (see below)
CI runs on Ubuntu and macOS. Windows is untested.
Quick start (Claude Code)
/plugin marketplace add costajohnt/oss-autopilot
/plugin install oss-autopilot@oss-autopilotRestart Claude Code, then:
/setup-ossSetup asks for your GitHub username, the languages and labels you care about, and how many PRs you want open at once. After that, run /oss whenever you want to check in.
About the first run. The plugin ships as source. The first /setup-oss or /oss installs dependencies and builds the CLI inside the plugin directory, so it needs npm (or pnpm) and a network connection, and it takes longer than later runs. If the build fails, see Troubleshooting.
Other ways to run it
Save your GitHub username once:
npx @oss-autopilot/core@latest init <your-github-username>Then add the server to your MCP client config:
{
"mcpServers": {
"oss-autopilot": {
"command": "npx",
"args": ["@oss-autopilot/mcp@latest"]
}
}
}The MCP server exposes 35 tools, 6 resources, and 4 prompts. @latest means you get new releases automatically; pin a version (@oss-autopilot/mcp@<version>) if you would rather update on your own schedule.
npx @oss-autopilot/core@latest init <your-github-username>
npx @oss-autopilot/core@latest daily # human-readable digest
npx @oss-autopilot/core@latest daily --json # structured output
npx @oss-autopilot/core@latest doctor # check token, state, rate limit
# or install it
npm install -g @oss-autopilot/core
oss-autopilot --helpEvery command accepts --json and returns { success, data, error, timestamp }, so it is easy to script.
npm install @oss-autopilot/coreimport { runDaily, runSearch } from '@oss-autopilot/core/commands';
const digest = await runDaily();
const issues = await runSearch({ maxResults: 10 });API reference: jcosta.tech/oss-autopilot.
The daily check
Run
/oss.The CLI fetches your open PRs from GitHub and classifies each one: failing CI, changes requested, unanswered maintainer comment, merge conflict, incomplete checklist, or waiting on the maintainer.
You get a short list with the PRs that need you first, and a menu of actions.
Pick one. An agent reads the thread and the diff, then drafts a reply or prepares a fix.
You read the draft and approve, edit, or discard it. Nothing is pushed or posted until you approve that specific action.
Repeat, or stop. Most days this is a few minutes.
If you are new to this, set maxActivePRs to 3 to 5. A few PRs you respond to quickly do better than many you let sit.
Commands
The plugin adds 9 slash commands:
Command | What it does |
| Daily check: what needs attention, then an action menu |
| Find issues to work on, matched to your languages and history |
| Unattended run that prepares fix branches locally and writes a morning report |
| Open the local dashboard in your browser |
| View or edit what the tool has learned about each repo's review preferences |
| Pre-push loop: lint, tests, parallel review agents, fix, repeat until clean |
| The same review loop for an implementation plan, before you write code |
| Configure preferences |
| Quick reference |
Commands: /oss, /oss-search, /oss-overnight, /oss-dashboard, /oss-guidelines, /pr-ready, /plan-ready, /setup-oss, /oss-help
The plugin also ships 8 specialized agents that Claude dispatches for you:
Agent | Job |
| Drafts replies to maintainer feedback |
| Diagnoses CI failures, conflicts, stale reviews; rebases when needed |
| Checks a PR against opensource.guide practices and the repo's own guidelines |
| Reviews your diff before you commit |
| Searches for and vets issues |
| Judges whether a repo is worth your time before you start |
| Looks at your history and suggests where to focus |
| Prepares one fix branch in a local worktree during |
Agents exist only in the Claude Code plugin. MCP and CLI users get the same underlying data through tools and commands.
For a deeper pre-push review, install the optional pr-review-toolkit plugin from the Claude Code marketplace. /pr-ready uses its reviewers in parallel when present and falls back to the built-in pre-commit-reviewer when not.
Finding new issues
/oss-search (or oss-autopilot search) looks for open issues that match your configured languages and labels, then vets each candidate: is it already claimed, is there a linked PR, does the repo merge outside contributions, how fast do maintainers respond. Search and vetting live in a separate package, oss-scout.
Two documents explain the scoring so you can see why a repo did or did not show up:
Repo scores: the history score (your own merged and closed PRs in that repo) and the health score (the repo's current activity, review speed, and merge rate).
Anti-LLM policy detection: repos whose CONTRIBUTING, CODE_OF_CONDUCT, or README say they do not accept AI-assisted contributions are skipped.
Overnight mode
/oss-overnight runs the daily check unattended. For PRs with a CI failure, a conflict, or requested changes, it prepares a fix branch in a local git worktree and runs the project's tests. It writes a report to ~/.oss-autopilot/reports/, and your next /oss shows it so you can decide what ships.
To schedule it on macOS:
oss-autopilot overnight schedule --install --hour 2--install writes a launchd plist to ~/Library/LaunchAgents/ and prints the launchctl bootstrap command that loads it. It does not load it for you. Without --install it only prints the plist. There is no built-in scheduler for Linux yet; commands/oss-overnight.md describes the invocation to put in a systemd timer.
Read this before scheduling it. The unattended run is started with an allowlist of tools and a deny list that blocks git push, gh pr comment, gh api, npm publish, and similar commands, and it cannot ask you questions. That stops a well-behaved model from writing to GitHub. It is not a sandbox: the run executes each project's test suite with your credentials available, the same as if you ran those tests yourself. If that is more trust than you want to give, run the job as a separate OS user with no push credentials. See commands/oss-overnight.md for the full threat model.
Dashboard
/oss-dashboard opens a local web UI at http://localhost:3000 with your PRs by status, contribution charts, and buttons to shelve or re-prioritize a PR. It binds to loopback only.
Without Claude Code, run it from the CLI (needs @oss-autopilot/core 3.28.1 or newer, and one daily run so there is data to show):
npx @oss-autopilot/core@latest daily
npx @oss-autopilot/core@latest dashboard serveConfiguration
Settings live in ~/.oss-autopilot/state.json under config. Change them with /setup-oss, or from the CLI:
oss-autopilot config # show everything
oss-autopilot config maxActivePRs 5 # set one valueSetting | Default | Description |
| (detected) | Your GitHub username |
| 10 | Open-PR count at which the tool suggests finishing before starting more |
| 1 | While none of your PRs in a repo have merged, search leaves the repo out once you have this many open PRs there, and the PR workflow warns before pushing another (0 = off) |
| 0 (off) | Same cap for every repo, including ones where your PRs have merged |
| 2 | How many implementations may run in the background at once, across sessions and machines (0 = off). Two never share a checkout |
| 30 | Days without activity before a PR is marked dormant |
| 50 | Minimum repo stars to count in stats and charts |
| (chosen at setup) | Languages for issue search |
| (chosen at setup) | Issue labels for issue search |
|
| Squash commits before merge ( |
|
| Repos to leave out of issue discovery. PRs already open there are still tracked; the pre-push repo-cap check warns before opening a new one |
|
| Orgs to leave out of issue discovery. PRs already open there are still tracked |
|
| Orgs whose PRs are not tracked at all (for example, your employer). Discovery is unaffected |
|
| Repos to rank lower in search without excluding them |
|
| Issue label types to rank higher in search (for example |
|
| Include documentation issues in search |
|
|
|
|
| After a PR merges, extract what the maintainers asked for into per-repo guidelines |
| (none) | Path to your own curated issue list |
|
| Categories to prioritize (nonprofit, devtools, and so on) |
|
| Orgs to prioritize |
Stats and badges. oss-autopilot stats prints your merged-PR numbers; --markdown gives a shareable report and --badge gives shields.io endpoint JSON.
Sync across machines (optional). State can be stored in a secret GitHub gist instead of only on disk. See oss-autopilot state --help. A secret gist is unlisted, not access-controlled, so anyone with the URL can read it.
How it works
One core, three front ends. The plugin calls the CLI with
--json. The MCP server imports the same functions. The dashboard is served by the CLI. They share one state file.The logic is code, not prompts. PR status, CI failure categories (your bug, fork limitation, auth gate, flaky infrastructure), staleness, and repo scores are computed in TypeScript with tests. The model reads structured JSON and does the parts that need language: reading a review thread, drafting a reply, proposing a fix.
Nothing is cached about your PRs. Each run fetches your open PRs fresh from GitHub's Search API and enriches them with CI status, review decisions, and conflict state. Local state holds your config, your merged and closed history, per-repo scores, and learned guidelines.
It is careful with the API. ETag-based HTTP caching, rate-limit backoff, bounded concurrency, and GraphQL batching keep a daily run well inside GitHub's limits.
Text from GitHub is treated as untrusted. Issue bodies, comments, and review text are fenced and labeled before an agent sees them.
More detail: ARCHITECTURE.md. Security model and reporting: SECURITY.md.
What it will and will not do on its own
Interactive ( | Unattended ( | |
Read your PRs, issues, CI logs | Yes | Yes |
Edit files in a local clone or worktree | When you pick an action | Yes, in a worktree it creates |
Run a project's tests | When you pick an action | Yes |
Push a branch | Only after you approve | Direct |
Post a comment, open or merge a PR | Only after you approve | Direct |
Send data anywhere other than GitHub | No | No |
In interactive use, approval is per action. Approving one reply does not approve the next one.
All data stays in ~/.oss-autopilot/ (files are written 0600, the directory 0700). There is no telemetry.
Troubleshooting
Start here. It checks your token, the CLI bundle, the state file, and your rate limit:
npx @oss-autopilot/core@latest doctorgh is missing or not logged in
brew install gh # macOS; see https://cli.github.com for other platforms
gh auth loginThe plugin's first-run build failed
find ~/.claude/plugins -name "oss-autopilot" -type d # locate the plugin
cd <that path>/packages/core
npm install
npm run bundleMy PRs do not show up
Run
/setup-ossand confirm the GitHub username.Only PRs you authored are tracked, and PRs to repos you own are skipped.
Check
untrackedOrgs.excludeReposandexcludeOrgsonly affect issue discovery, andminStarsonly affects stats and charts.
Updating
Plugin:
/plugin update oss-autopilotMCP and CLI via
npx ...@latest: nothing to do
Found a bug? Open an issue with the output of doctor --json.
Limitations
GitHub only. No GitLab, Bitbucket, or other forges.
1,000-result 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 are not counted.
Single user. It tracks one person's PRs. No team views or shared state.
Overnight scheduling is macOS only out of the box.
Contributing
Bug fixes, new agents, CLI improvements, and documentation are all welcome. CONTRIBUTING.md has setup instructions.
git clone https://github.com/costajohnt/oss-autopilot.git
cd oss-autopilot
pnpm install
pnpm test
pnpm start -- daily --json # run the CLI from source
claude --plugin-dir . # load your checkout as the pluginThe diagrams in this README are generated from the JSON files in docs/diagrams/ with archify. Regenerate them with node docs/diagrams/export-svg.mjs.
About
Built and used daily by costajohnt.
License
MIT
Available Tools
20 toolscheck-setupARead-only
Check whether OSS Autopilot is properly set up and configured. Returns setup status and any missing configuration.
Inputs: no named parameters.
claimA
Claim a GitHub issue by posting a comment expressing intent to work on it.
Inputs: issueUrl (required), message.
commentsARead-only
Fetch and display comments on a pull request, including review comments and issue comments.
Inputs: prUrl (required), showBots.
configAIdempotent
Get or set OSS Autopilot configuration values. With no args, shows all config. With key and value, sets the value.
Inputs: key, value.
dailyA
Run daily PR monitoring check. Fetches all open PRs, enriches with CI status, reviews, and conflicts, then returns a prioritized summary.
Inputs: no named parameters.
dismissA
Dismiss a GitHub issue so it no longer appears in notifications.
Inputs: url (required).
initA
Initialize OSS Autopilot with a GitHub username. Creates the state file and sets up initial configuration.
Inputs: username (required).
moveA
Move a PR between states: attention (need attention), waiting (waiting on maintainer), shelved (hidden), or auto (reset to computed status).
Inputs: prUrl (required), target (required).
postC
Post a comment on a GitHub issue or pull request.
Inputs: url (required), message (required).
readA
Mark PR notifications as read. Requires either prUrl or all to be specified.
Inputs: all, prUrl.
searchARead-only
Search GitHub for beginner-friendly open-source issues to contribute to. Returns issues matching configured languages and interests.
Inputs: maxResults.
setupB
Run OSS Autopilot setup to configure preferences like languages, interests, and contribution goals.
Inputs: set, reset.
shelveA
Shelve a PR to temporarily hide it from daily checks and status reports without untracking it.
Inputs: prUrl (required).
startupB
Run startup checks including GitHub auth verification, state file validation, and configuration status.
Inputs: no named parameters.
statusARead-only
Show current PR tracking status including open PRs, shelved PRs, and dismissed issues.
Inputs: offline.
trackA
Start tracking a pull request. Adds the PR to your monitored list so it appears in daily checks and status reports.
Inputs: prUrl (required).
undismissA
Undismiss a previously dismissed issue, re-enabling notifications.
Inputs: url (required).
unshelveA
Unshelve a previously shelved PR, returning it to active monitoring.
Inputs: prUrl (required).
untrackADestructive
Stop tracking a pull request. Removes the PR from your monitored list.
Inputs: prUrl (required).
vetARead-only
Analyze a GitHub issue to determine if it is a good candidate for contribution. Checks for clarity, scope, existing assignees, and staleness.
Inputs: issueUrl (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools are distinct, but several clusters overlap: init/setup/config/check-setup/startup all concern configuration, and move overlaps with shelve/unshelve by supporting a shelved state. Descriptions clarify intent, but an agent could easily select the wrong tool in these areas.
The set uses a consistent lowercase command style with clear un- reversals (untrack, unshelve, undismiss). A few names are nouns or adjectives (status, comments, daily, startup) and check-setup is hyphenated, but the overall pattern is readable and predictable.
At 20 tools, the server is on the heavy side for its scope. The count is justifiable given PR tracking, issue triage, state management, and setup clusters, but some tools (check-setup/startup, shelve/unshelve vs move) could be consolidated.
The core workflow is covered: discover issues, vet them, claim/comment, track PRs, run daily checks, and manage state via shelve/dismiss/move. Minor gaps exist such as no explicit reset/uninitialize and no dedicated single-PR detail fetch, but agents can work around these.
Maintenance
Related MCP Connectors
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
Related MCP Servers
- AlicenseAqualityDmaintenanceOne MCP that turns Claude Code into your whole dev stack by swallowing other MCP servers, delegating to Codex & Gemini on your CLI subscriptions, remembering projects in a searchable knowledge graph, and carrying setup across sessions — secret-free by design.234MIT
- AlicenseNot gradedqualityAmaintenanceTurns GitHub Projects v2 into an agentic project management layer where AI coding agents register, atomically claim and track tasks, heartbeat, review each other's work, and operate within token budgets, all backed by GitHub-native storage with no external infrastructure. It also gives humans AI-powered PRD generation, PRD-to-issues pipelines, sprint planning, triage, roadmap creation, and requirements traceability across 20 compound tools exposing 169 actions, plus MCP resources, prompts, and sampling support.272 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents and human managers to coordinate work on GitHub Projects v2 through 20 tools and 169 actions for autonomous task checkout, heartbeats, reviews, token budgets, PRD generation, sprint planning, issue triage, and PRD-to-issues pipelines, backed by GitHub-native storage and MCP resources/prompts.272 npmMIT
- AlicenseNot gradedqualityAmaintenanceTurns GitHub Projects v2 into an autonomous agentic task substrate where AI coding agents register, atomically claim tasks, heartbeat, submit and review work products, and operate under per-agent token budgets — all stored natively in GitHub issues, fields, and comments with no external infrastructure. It also gives humans AI-powered PRD generation, task breakdown and materialization, sprint planning, issue triage, and requirements traceability across 20 compound tools exposing 169 actions, plus MCP resources and prompts.272 npmMIT