ContribOS is an open-source contribution companion tool that provides both a guide and an MCP server. It is positioned to help new open-source contributors gain trust and successfully merge PRs in the AI era. Entering 2026, writing code is no longer the hard part of contributing: AI has made PRs cheap, so maintainers set PR limits, sponsor lists, and AI policies, and the merge rate for newcomers has declined accordingly. ContribOS's goal is to make your PR worth a maintainer's time. It will not open PRs, post comments, or claim issues for you, nor will it write descriptions for you; it only points the way, and you decide for yourself.
Main capabilities:
- Policy radar (policy.py): builds a repository policy view from contribution docs, AI policies, templates, sponsor lists, CI configuration, and history. Every conclusion points to a specific file and line number (or git history) so you can verify it yourself.
- Evidence-based brief (brief.py): ranks files by rare-word matches in the code, path matches, and files touched by similar historical PRs, and finds related tests through co-change history.
- Pre-submission check (check.py): includes a pre-submission check, comprehension verification, and PR draft.
- Environment diagnosis (setup_doctor.py): generates installation steps based on CI and docs, and diagnoses failure causes.
- Contribute-ability check (find.py): evaluates issue claimability, repository welcomingness, and response speed.
- Proposal drafting (claim.py): drafts proposals and sponsor introductions.
- Proof of understanding (proof.py): runs tests both with and without your changes (files are restored in finally).
- Tone check (tone.py): checks the text you are about to publish.
- Local agent rules (agent_rules.py): generates local agent skills and hooks.
- Review coaching (review.py): classifies review comments, drafts replies, and tracks follow-up implementation.
- Contribution record (record.py): generates a contribution record as markdown and a self-contained HTML page.
How to use: most features that can run offline only need git, including policy, brief --title, claim --title, setup, check, bench, and review --data. Use --offline to skip the API, use --update to pullFetch new submissions. Clones and index caches are stored in ~/.cache/contribos (can be overridden with CONTRIBOS_CACHE). Optional AI summaries are enabled via the environment variable CONTRIBOS_LLM=anthropic (requires ANTHROPIC_API_KEY) or CONTRIBOS_LLM=openai (requires OPENAI_API_KEY), and CONTRIBOS_MODEL can optionally be set. The model only interprets evidence already collected by ContribOS; any sentence citing files outside the evidence is discarded. repo.py handles cached clones, reading arbitrary revisions via git show and git grep without needing a checkout. precedent.py builds a SQLite index of main-branch changes (squash and merge PRs), the files they touch, and the issues they fix. github.py is an optional API client, and all callers handle its absence. mcp_server.py is a zero-dependency MCP stdio server.
Use cases: suitable for new contributors who want to improve their merge rate in repositories where maintainers set AI policies, PR limits, and allowlists; also suitable for people who want to understand the specific way a repository accepts changes, self-check their understanding before submitting, and build a verifiable contribution record. The project welcomes contributions, including Hacktoberfest; it is recommended to start with issues labeled good first issue, comment to claim, then read CONTRIBUTING.md, which covers the rules for claiming issues, disclosing AI use, and running tests.
Verification and limitations: policy, brief, claim --title, setup, check, bench, and mcp have been tested on real repositories (Flask, pytest, Ghostty); on 2026-10-01, find, claim <url>, and record were tested against the live GitHub API; and agent-rules, check --verify-test, tone, and policy radar v2 were tested in temporary git repositories. Tests are run with python -m unittest discover -s tests, with 59 tests total, and CI covers Linux, macOS, and Windows. Benchmarks (2026-09-28, offline, using PR titles to refer to issues) show that matching against historical PRs helps little with file location, confirming the judgment that "finding files is a general capability"; the next benchmark needs real issue text and review comments, which requires GITHUB_TOKEN. The release process is: update the version number in pyproject.toml, contribos/init.py, and the two places in server.json, run the tests, then commit and push, then tag and release.