oss-autopilot

OSS Autopilot is an open-source contribution management tool designed to help developers who frequently participate in open-source projects track and manage their own GitHub Pull Requests (PRs), preventing PRs from stalling due to being forgotten. It offers three ways to use it: a Claude Code plugin, an MCP server, and a standalone CLI.

Purpose

If you contribute code to multiple projects at the same time, PRs can easily go stale without you realizing it: maintainers request changes, CI fails after a rebase, branches develop conflicts, and you might not notice until two weeks later. OSS Autopilot checks all your open PRs on GitHub, categorizes them into "needs your action" and "waiting on others," and provides assisted actions for the PRs that need your action.

Main capabilities

• PR categorization: Fetches your open PRs from GitHub and categorizes them as: CI failure, changes requested, unanswered maintainer comments, merge conflicts, incomplete checklist, waiting on maintainer.
• Assisted handling: For PRs that need your action, the agent reads the discussion thread and diff, then drafts a reply or prepares a fix. You must approve, edit, or discard each draft one by one; nothing is pushed or posted without approval.
• Discovering new issues:/oss-search(or oss-autopilot search) finds open issues matching your configured languages and labels, and reviews each candidate: whether it has already been claimed, whether there is a linked PR, whether the repository accepts external contributions, and how responsive the maintainers are. Search and review are handled by the standalone package oss-scout .
• Unattended nightly checks:/oss-overnight runs daily checks unattended. For PRs with CI failures, conflicts, or requested changes, it prepares a fix branch in a local git worktree and runs the project tests, writing a report to ~/.oss-autopilot/reports/, which is shown the next time /oss .
• Local dashboard:/oss-dashboard opens a local Web UI at http://localhost:3000 , showing PRs by status, contribution charts, and buttons to shelve or reorder PRs. It binds only to the loopback address.
• Stats and badges:oss-autopilot stats prints the number of merged PRs;--markdown generates a shareable report,--badge generates shields.io endpoint JSON.
• Cross-machine sync (optional): State can be stored in a secret GitHub gist instead of only on disk. A secret gist is unlisted rather than access-controlled, and anyone with the URL can read it.

How to use

Quick start (Claude Code)

Prerequisites: Node.js 22 or newer; GitHub CLI installed and logged in (gh auth login), or GITHUB_TOKENset in the environment; the plugin requires Claude Code, as well as npm and network access on first run. CI runs on Ubuntu and macOS; Windows is untested.

Restart Claude Code, then run /setup-oss to set up; setup will ask for your GitHub username, the languages and labels you follow, and the number of simultaneously open PRs. After that, run /oss to check.

First-run notes: The plugin is published as source code, and the first /setup-oss or /oss will install dependencies and build the CLI inside the plugin directory, requiring npm (or pnpm) and a network connection, and taking longer than subsequent runs.

Other ways to run

• MCP server: Save your GitHub username once, then add the server to your MCP client configuration. The MCP server exposes 30 tools, 6 resources, and 4 prompts.@latest automatically fetches new versions; you can pin a version (e.g. @oss-autopilot/mcp@5.7.4).
• CLI: Each command accepts --json, returning { success, data, error, timestamp }, making it easy to script. API reference: jcosta.tech/oss-autopilot.

Daily check flow

1. The CLI fetches open PRs from GitHub and categorizes them.
2. You get a short list, with PRs that need you prioritized, plus a menu of actions.
3. Choose an action. The agent reads the thread and diff, then drafts a reply or prepares a fix.
4. You read the draft and approve, edit, or discard it. Nothing is pushed or posted without approval.
5. Repeat or stop. Most days take only a few minutes.

New users should set maxActivePRs to 3 to 5.

Plugin commands and agents

The plugin adds 9 slash commands:/oss、/oss-search、/oss-overnight、/oss-dashboard、/oss-guidelines、/pr-ready、/plan-ready、/setup-oss、/oss-help.

The plugin also ships with 8 specialized agents, dispatched by Claude. Agents exist only in the Claude Code plugin; MCP and CLI users get the same underlying data through tools and commands.

For deeper pre-push review, you can install the optional pr-review-toolkit plugin from the Claude Code marketplace./pr-ready uses its reviewers in parallel when present, otherwise falls back to the built-in pre-commit-reviewer.

Setup

Setup is located under ~/.oss-autopilot/state.json in config . It can be changed via /setup-oss or the CLI.

Architecture

One core, three frontends: the plugin calls the CLI via --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 state, CI failure categories (your bug, fork restriction, auth gate, flaky infrastructure), staleness, and repo scoring are all computed and tested in TypeScript. The model reads structured JSON and handles the parts that require language: reading review threads, drafting replies, proposing fixes.

PR information is not cached. Each run fetches open PRs fresh from the GitHub Search API and supplements them with CI status, review decisions, and conflict status. Local state stores configuration, merge and close history, per-repo scoring, and learned guidelines.

Be careful with the API: ETag-based HTTP caching, rate-limit backoff, bounded concurrency, and GraphQL batching keep daily runs well within GitHub limits.

Text from GitHub is treated as untrusted. Issue bodies, comments, and review text are fenced and marked before the agent sees them.

Security and privacy

When used interactively, approval is per action. Approving one reply does not approve the next. All data stays in ~/.oss-autopilot/(file permissions 0600, directory 0700). No telemetry.

Unattended runs use a tool allowlist and denylist that block commands such as git push、gh pr comment、gh api、npm publish and cannot ask questions. This prevents a well-behaved model from writing to GitHub, but it is not a sandbox: the run executes each project's test suite using your credentials. If you don't trust it enough, run it as a separate OS user with no push credentials. See commands/oss-overnight.mdfor the full threat model.

Troubleshooting

• Start with doctor to check the token, CLI package, state file, and rate limits.
• gh is missing or not logged in.
• The plugin fails to build for the first time.
• PRs don't show up: run /setup-oss to confirm the GitHub username; only PRs you authored are tracked; check excludeRepos、excludeOrgs and minStars.
• Updates: plugin /plugin update oss-autopilot; MCP and CLI require no action via npx ...@latest ; configuration is preserved.
• Found a bug? File an issue with doctor --json output.

Use Cases

• Developers who contribute code to multiple open source projects at the same time and need to track the status of multiple PRs.
• Contributors who want to automatically discover new issues that match their skills and interests.
• Scenarios that require unattended checking of PR status and preparing fixes (macOS).
• Users who want to obtain contribution statistics and badges.

Limitations

• Only GitHub is supported; GitLab, Bitbucket, or other platforms are not supported.
• The GitHub Search API returns at most 1,000 results per query. If there are more than 1,000 open, merged, or closed PRs, the oldest ones will not be counted.
• Single-user; tracks one person's PRs, with no team view or shared state.
• Unattended scheduling works out of the box only on macOS.
• Windows is untested.
• The first run requires npm and a network connection, and the build takes a long time.
• Secret gists are unlisted rather than access-controlled, and anyone with the URL can read them.
• Unattended runs are not sandboxed and execute tests using your credentials.