contribos
ContribOS is an MCP server that helps open-source contributors research repositories, prepare changes, and handle review while leaving posting and PR creation to the human.
Check a repo's contribution policy, including AI rules, vouch gates, tests, changelog, sign-off, and cited
file:lineevidence.Build an evidence-backed brief for an issue: files to read, similar past PRs, related tests, files to avoid, house rules, and likely review questions.
Generate exact setup and test steps from a repo's CI and contributing docs.
Diagnose failed installs or test runs.
Run pre-submit checks on a local branch: scope, tests, changelog, sign-off, debug leftovers, AI disclosure, explanation coverage, competing PRs, and test verification.
Coach review responses by classifying reviewer comments, showing pointed-at code, drafting replies, and tracking unanswered comments.
Draft a pre-coding issue proposal or vouch introduction for the human to rewrite and post.
Check text for machine-written tells, length, and missing questions before posting.
Find open issues where newcomers are welcome, with takeability evidence.
Integrates with the GitHub API (via GITHUB_TOKEN) to search and score open issues, inspect repo policies, vouch lists and outside-PR merge rates, look up similar past PRs and reviewer comments, track competing PRs and failing CI on a PR, and build a public verified record of merged PRs, review responses and AI disclosure for a user.
Optional LLM provider (CONTRIBOS_LLM=openai with OPENAI_API_KEY) used to generate grounded plain-language summaries of the evidence ContribOS has already collected, with any claim citing files outside that evidence discarded.
ContribOS
Get trusted. Get merged. Come back. ContribOS helps new open-source contributors earn trust. It finds where you're welcome, shows how this repo wants the change done, checks that you truly understand your change, coaches you through review, and turns merged PRs into a record the next maintainer can verify.
In 2026, writing code is not the hard part of contributing. AI made PRs cheap, maintainers answered with PR caps, vouch lists and AI policies, and newcomer merge rates fell. ContribOS makes your PR worth a maintainer's time.
ContribOS never opens PRs, posts comments or claims issues for you, and it never writes your explanation. It points, and you decide.
If ContribOS saved you a rejected PR, a ⭐ on this repo helps other contributors find it.
See it work
Before you open a PR, ask the repo what it expects. This is real output from contribos policy pallets/flask, trimmed (snapshot from 6 Oct 2026; run it yourself for current results):
# Contribution policy: pallets/flask
## AI policy
No written AI policy found. Disclosing AI use is still the courteous default.
## Tests
Changes are expected to come with tests.
- `.github/pull_request_template.md:20`: - Add tests that demonstrate the correct behavior of the change. Tests
## Changelog
Changes usually need a changelog or news entry.
- `.github/pull_request_template.md:23`: - Add an entry in CHANGES.rst summarizing the change and linking to the issue.
## Tests in practice
50% of recent code PRs also changed tests.
- `git history`: 19 of 38 recent code-changing PRs
## Outside PRs
2 of the last 49 closed PRs from non-members landed.Every claim points at a file and line (or git history), so you can check it yourself. ContribOS points, you decide.
pip install contribos
contribos policy pallets/flaskRelated MCP server: OpenCollab MCP
The journey
Step | Command | What you get |
Find |
| Open issues sorted into Good bet / Possible / Skip, each with evidence: claimed? open PR? maintainer active? clear? Plus repo welcome: archived, vouch list, AI policy, outside-PR merge rate, how long outside PRs wait for a first human reply, how many stall, a stale bot, and your own open PRs there |
Rules |
| The repo's AI policy, disclosure format ( |
Propose |
| A short proposal to post before coding: likely files, a similar-size past PR, where the test goes, and one real question. Warns about taken issues, no maintainer yet, good-first-issue AI rules and issue-first rules. If the repo has a vouch list, it drafts the introduction first |
Tone |
| Flags machine-written tells (delve, buzzwords, assistant openers, filler), length, a missing question and leftover placeholders in anything you're about to post |
Agent rules |
| Teaches your coding agent this repo's rules: a SKILL.md for Claude Code, Codex, Copilot and Cursor, a hook that stops the agent opening PRs or posting comments, and a commit-msg hook for sign-off and the AI-disclosure trailer. All local-only, excluded from git |
Setup |
| Exact steps taken from the repo's CI and contributing guide: runtime version, install, services, env vars, test and lint commands |
Diagnose |
| What a failure means: missing dependency, wrong version, service down, env var, native build tools, flaky test, or a real test failure (and how to check it isn't yours) |
Understand |
| Files to read with the reasons each was picked, similar past PRs and what reviewers said, related tests, look-alike files to leave alone, house rules, and likely review questions. Add |
Prove |
| Pre-submit review: scope versus similar past changes, tests, changelog, sign-off, debug leftovers, AI policy and disclosure trailers, competing PRs for the same issue. |
Respond |
| Each reviewer comment classified (blocking, change, question, nit…), the code it points at, the house rule it echoes, a reply draft, what's still unanswered and for how long, and failing CI |
Grow |
| A public, linkable record: merged PRs, change requests, whether you answered every review comment, whether you explained your change and disclosed AI use |
Agents |
| Nine MCP tools for Claude Code, Cursor, Codex and others (policy, brief, setup, diagnose, check, review, find, claim, tone), taking text as input where an agent has text: |
Install
pip install contribosYou need Python 3.10+ and git. There are no other dependencies.
Set GITHUB_TOKEN for find, claim or brief from an issue URL, review, and record:
export GITHUB_TOKEN=... # macOS, Linux$env:GITHUB_TOKEN = "..." # Windows PowerShellpolicy also runs without a token, but it skips pull-request signals and says so at the top of its output.
Everything that can run offline does: policy, brief --title, claim --title, setup, check, bench and review --data need only git. Add --offline to skip the API, and --update to fetch new commits. Clones and indexes are cached in ~/.cache/contribos (CONTRIBOS_CACHE).
Optional AI summaries: CONTRIBOS_LLM=anthropic (with ANTHROPIC_API_KEY) or CONTRIBOS_LLM=openai (with OPENAI_API_KEY), plus optional CONTRIBOS_MODEL. The model only explains evidence ContribOS already gathered. Any sentence citing a file outside that evidence is dropped.
How it works
repo.pyhandles cached clones. It reads any revision withgit showandgit grep, so no checkout is needed.precedent.pybuilds a SQLite index of main-line changes (squash and merge PRs), the files they touched, and the issues they fixed.policy.pyis the policy radar, built from contribution docs, AI policies, templates, vouch lists, CI config and history.brief.pyranks files by rare-term matches in code, path matches, and files touched by similar past PRs. It also finds related tests via co-change history.check.pyis the pre-submit check, the proof-of-understanding check and the PR draft.setup_doctor.pyproduces setup steps from CI and docs, and diagnoses failures.find.pychecks issue takeability, repo welcome and responsiveness.claim.pydrafts the proposal and vouch introduction.proof.pyruns a test with and without your change (files restored infinally).tone.pychecks text you're about to post.agent_rules.pywrites the local agent skill and hooks.review.pyclassifies review comments, drafts replies and tracks follow-through.record.pybuilds the contribution record (markdown plus a self-contained HTML page).llm.pyis the optional provider layer (Anthropic or OpenAI) with citation grounding.mcp_server.pyis a dependency-free MCP stdio server.github.pyis the optional API client. Every caller handles its absence.bench.pyruns the history benchmark.
Benchmark (2026-09-28, offline, PR titles standing in for issues)
Repo | Brief hit@5 | Grep-only hit@5 |
pallets/flask (30 PRs) | 0.77 | 0.73 |
pytest-dev/pytest (30 PRs) | 0.87 | 0.87 |
Matching against past PRs barely improves file finding, which supports the plan's bet that finding files is a commodity. The value is in how past PRs did it and what reviewers asked. The next benchmark needs real issue text and review comments, which requires GITHUB_TOKEN.
Contributing
Contributions are welcome. Start with issues labelled good first issue, comment on one to claim it, and read CONTRIBUTING.md first. It covers claiming an issue, disclosing AI use, and running the tests. To see these rules the way ContribOS reads them:
contribos policy adityatiwari101104/contribosStatus
Tested on real repos (Flask, pytest, Ghostty):
policy,brief,claim --title,setup,check,bench,mcp.Tested against the live GitHub API on 2026-10-01:
find(scored issue takeability and maintainer response medians onmaximilianfeix/proxy-scraperandbrekkylab/backlot),claim <url>(drafted pre-coding proposals with past similar PRs and file targets), andrecord(verified public merged PR portfolio for@adityatiwari101104).Tested on temporary git repos:
agent-rules(git status stays clean, the guard blocksgh pr create, the commit-msg hook enforces sign-off and the trailer),check --verify-test,tone, policy radar v2.Tests:
python -m unittest discover -s tests(85 tests, CI matrix on Linux, macOS, and Windows).
Releasing
Bump the version in
pyproject.toml,contribos/__init__.pyand both places inserver.json.Run
python -m unittest discover -s tests, then commit and push.Tag and publish:
git tag v<version>
git push origin v<version>
python -m build
twine upload dist/*
mcp-publisher login github
mcp-publisher publishAvailable Tools
9 toolscontribos_briefC
Evidence-backed contribution brief for an issue: files to read with reasons, similar past PRs, related tests, look-alike files to avoid, house rules and likely review questions.
Inputs: repo, title, issue_url.
contribos_checkB
Pre-submit review of the local branch against the repo's rules and history: scope versus similar past changes, tests, changelog, sign-off, debug leftovers, AI policy, and whether the contributor's own explanation covers the change, AI-disclosure trailers, competing PRs, and (with verify_test) whether the test fails without the fix. Do not write the explanation for the user.
Inputs: base, path, issue, ai_note, +3 more.
contribos_claimB
Draft the short proposal a contributor posts on an issue before coding (and a vouch introduction where the repo needs one). The human rewrites and posts it; never post it.
Inputs: repo, title, issue_url.
contribos_diagnoseB
Explain a failed install or test run: missing dependency, wrong version, service not running, missing env var, flaky test, or a real test failure.
Inputs: log, output_file.
contribos_findC
Find open issues where a newcomer is actually welcome, with takeability evidence.
Inputs: repos, topic, language.
contribos_policyA
What a GitHub repository expects from outside contributors: AI policy, vouch/trust gates, claim-first norms, tests, changelog, sign-off, activity. Every finding cites file:line. Call this before starting work on any repo.
Inputs: repo (required), json.
contribos_reviewA
Review coach for an open PR: classifies each reviewer comment, shows the code it points at, drafts replies, and lists comments still waiting on the author.
Inputs: data, path, pr_url.
contribos_setupC
Exact steps to set up and test a repository, taken from its CI and contributing docs.
Inputs: repo (required).
contribos_toneB
Check text the human is about to post for machine-written tells, length, and a clear question. Points at problems; the human rewrites.
Inputs: text (required), kind.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct stage of the contribution workflow (find, policy, brief, setup, diagnose, claim, tone, check, review). Overlaps like check-vs-review and claim-vs-tone are resolved by the descriptions, which clearly bound one to pre-submit local work and the other to open PRs, and one to drafting versus checking text.
Every tool follows the identical contribos_verb pattern with a single lowercase word (policy, brief, setup, diagnose, check, review, claim, tone, find). No deviations in casing or verb style.
Nine tools is well within the ideal 3-15 range and each maps to a discrete workflow step with no filler. The count feels deliberately scoped to the contribution lifecycle rather than padded.
The surface covers discovery, repo-policy intake, briefing, setup, diagnostics, claiming, tone, pre-submit review, and PR review commentary. Deliberately omits automated posting (human stays in the loop), leaving only minor gaps such as a way to locate repos or matching to review history.
Maintenance
Related MCP Connectors
Find open-source GitHub issues to contribute to, matched to your skills; you approve every PR.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Open-source licence risk checks for AI coding agents and dependency trees.
Git-native policy layer for AI agents: check_action verdicts against rules approved via PR.
Related MCP Servers
- AlicenseBqualityAmaintenanceOpen source contribution manager — tracks PRs across repos, discovers contributable issues, diagnoses CI failures, and drafts maintainer responses. 21 MCP tools, 5 resources, 3 prompts. Ships as CLI, MCP server, and Claude Code plugin.2030MIT
- AlicenseAqualityBmaintenanceEnables developers to find personalized open-source contributions by analyzing GitHub profiles and matching them with relevant 'good first issues' and beginner-friendly repositories. Provides comprehensive contribution tooling including repository health scoring, setup difficulty assessment, impact estimation, and automated PR planning.102246MIT
- AlicenseAqualityDmaintenanceGuides AI agents through open-source contribution workflows, from finding issues to submitting PRs, while keeping decision-making and coding with the human contributor.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to evaluate real OSS contribution opportunities by scoring issues on availability, competing PRs, staleness, and maintainer sentiment, including live feasibility checks for any repository.MIT