oss-autopilot

<p align="center">
  <img src="assets/hero-light.svg" alt="OSS Autopilot" width="600">
</p>

<p align="center">
  <em>An AI-powered workflow engine for managing open source contributions at scale — built as a Claude Code plugin, MCP server, and standalone CLI.</em>
</p>

<p align="center">
  <img src="https://github.com/costajohnt/oss-autopilot/actions/workflows/ci.yml/badge.svg" alt="CI">
  <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
  <img src="https://img.shields.io/badge/TypeScript-strict-blue?logo=typescript&logoColor=white" alt="TypeScript">
  <img src="https://img.shields.io/node/v/@oss-autopilot/core" alt="Node.js">
  <img src="https://img.shields.io/github/stars/costajohnt/oss-autopilot?style=flat" alt="Stars">
  <img src="https://img.shields.io/github/last-commit/costajohnt/oss-autopilot" alt="Last Commit">
</p>
<p align="center">
  <a href="https://www.npmjs.com/package/@oss-autopilot/core"><img src="https://img.shields.io/npm/v/@oss-autopilot/core" alt="npm @oss-autopilot/core"></a>
  <a href="https://www.npmjs.com/package/@oss-autopilot/core"><img src="https://img.shields.io/npm/dw/@oss-autopilot/core" alt="npm downloads"></a>
  <a href="https://www.npmjs.com/package/@oss-autopilot/mcp"><img src="https://img.shields.io/npm/v/@oss-autopilot/mcp" alt="npm @oss-autopilot/mcp"></a>
</p>

---

**Built and used daily by [costajohnt](https://github.com/costajohnt)** — 3rd biggest contributor to [Ink](https://github.com/vadimdemedes/ink) (the React CLI framework behind Claude Code, Gemini CLI, and Codex — 32k+ stars) and repeat contributor to [Homebrew](https://github.com/Homebrew/homebrew-cask).

<p align="center">
<a href="https://github.com/costajohnt/oss-autopilot">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://oss-widgets.vercel.app/api/card/costajohnt?theme=dark&minStars=50" />
  <source media="(prefers-color-scheme: light)" srcset="https://oss-widgets.vercel.app/api/card/costajohnt?theme=light&minStars=50" />
  <img alt="OSS Stats" src="https://oss-widgets.vercel.app/api/card/costajohnt?theme=dark&minStars=50" width="495" />
</picture>
</a>
</p>

<p align="center">
<a href="https://github.com/costajohnt/oss-widgets">
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://oss-widgets.vercel.app/api/top-repos/costajohnt?theme=dark&minStars=50" />
  <source media="(prefers-color-scheme: light)" srcset="https://oss-widgets.vercel.app/api/top-repos/costajohnt?theme=light&minStars=50" />
  <img alt="Top Contributed Repos" src="https://oss-widgets.vercel.app/api/top-repos/costajohnt?theme=dark&minStars=50" width="495" />
</picture>
</a>
</p>

---

## What It Does

OSS Autopilot monitors all your open PRs across GitHub, alerts you when maintainers leave feedback, helps you draft responses, diagnoses CI failures, and finds new issues matched to your contribution history. It's the workflow engine behind the stats above.

![OSS Autopilot Demo](docs/images/demo.gif)

### Interactive Dashboard

![dashboard-demo](https://github.com/user-attachments/assets/680ce6d6-8192-499a-b85e-f2686319b961)

A Preact SPA that auto-opens when you run `/oss` — PR management, charts, contribution stats, and status overrides. Also available standalone: `npx @oss-autopilot/core dashboard serve`.

---

## Engineering Highlights

```
┌──────────────────────────────────────────────────┐
│  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,    │  │
│  │ 25 tools     │  │ actions                   │  │
│  │ 5 resources  │  │                           │  │
│  │ 3 prompts    │  │                           │  │
│  └──────┬───────┘  └────────────┬─────────────┘  │
│         │                       │                │
│  ┌──────┴───────────────────────┴─────────────┐  │
│  │ Core Library — @oss-autopilot/core         │  │
│  │ PR monitoring, issue discovery, state mgmt │  │
│  │ GitHub API, CLI, structured JSON output    │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
└──────────────────────────────────────────────────┘
```

**Monorepo with three npm packages** — pnpm workspaces with each package independently publishable to npm. Core library, MCP server, and interactive Preact dashboard with shared types.

**Three deployment models** — Claude Code plugin with 7 specialized agents, MCP server for Cursor/Claude Desktop/Codex/Windsurf, and a standalone CLI with `--json` structured output. Same core, different interfaces.

**Deterministic core, AI orchestration layer** — Critical logic (PR status classification, CI failure analysis, state management) lives in tested TypeScript, not in prompts. The CLI returns structured JSON that agents consume. CI failures are categorized into a deterministic taxonomy — actionable vs. fork limitation vs. auth gate vs. infrastructure — rather than asking an LLM each time. 1,762 tests validate the core independently of any LLM.

**Production-grade GitHub API integration** — ETag-based HTTP caching, automatic rate limit backoff with retries, bounded concurrency pools, and paginated fetching. Handles the full complexity of fork-based contribution workflows: correct diff ranges, squash commit counting, and `--head` flag handling for cross-fork PRs. Designed to run daily without hitting API limits.

**Human-in-the-loop guardrails** — Nothing is posted to GitHub without explicit approval. AI drafts responses but the contributor always reviews before sending. Pre-commit review gates catch issues before they reach maintainers. Factual claims in draft comments are verified against the actual diff before presenting to the user.

**Modular extraction** — Issue discovery and vetting grew complex enough to extract into its own npm package ([oss-scout](https://github.com/costajohnt/oss-scout)). Connected via a bridge pattern that maps state between the two systems, following the same approach used by the broader ecosystem of extraction-and-reconnect patterns.

**Fresh-fetch architecture** — PRs aren't stored locally. Every run fetches live data from GitHub's Search API and enriches each PR with CI status, review decisions, merge conflict detection, maintainer comment classification, and checklist completion. No stale data, no sync bugs.

**Security discipline** — State files written with `0o600` permissions, data directory created with `0o700`. Concurrent state write protection prevents corruption from parallel runs. Runtime schema validation via Zod on every state file read. XSS prevention tested. Input validation hardened across CLI arguments and API responses.

**Automated release pipeline** — Conventional commits feed into release-please for automatic versioning and changelogs, with CI/CD publishing to npm on merge. 70+ published releases since March 2026, with 150+ changelog versions spanning the full v0.1.0 → v1.11.0 history.

Every feature in the list above was driven by real usage — capacity warnings came from overcommitting, "skip comment when code speaks for itself" came from over-commenting, diminishing returns detection came from spending too long searching. The tool is shaped by the contributions it manages.

---

## Install & Usage

**Claude Code Plugin (recommended):**

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

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

<details>
<summary><strong>MCP Server</strong> (Cursor, Claude Desktop, Codex, Windsurf)</summary>

First initialize your GitHub userna

[truncated…]