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. See ../plan-v4.md and ../plan-v5-research.md for the full reasoning.

ContribOS never opens PRs, posts comments or claims issues for you, and it never writes your explanation. It points, and you decide.

The journey

Install

pip install -e .          # Python 3.10+, git. No other dependencies.
export GITHUB_TOKEN=...   # needed for find, claim/brief from an issue URL, review, record

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.py handles cached clones. It reads any revision with git show and git grep, so no checkout is needed.
• precedent.py builds a SQLite index of main-line changes (squash and merge PRs), the files they touched, and the issues they fixed.
• policy.py is the policy radar, built from contribution docs, AI policies, templates, vouch lists, CI config and history.
• brief.py ranks 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.py is the pre-submit check, the proof-of-understanding check and the PR draft.
• setup_doctor.py produces setup steps from CI and docs, and diagnoses failures.
• find.py checks issue takeability, repo welcome and responsiveness.
• claim.py drafts the proposal and vouch introduction.
• proof.py runs a test with and without your change (files restored in finally).
• tone.py checks text you're about to post.
• agent_rules.py writes the local agent skill and hooks.
• review.py classifies review comments, drafts replies and tracks follow-through.
• record.py builds the contribution record (markdown plus a self-contained HTML page).
• llm.py is the optional provider layer (Anthropic or OpenAI) with citation grounding.
• mcp_server.py is a dependency-free MCP stdio server.
• github.py is the optional API client. Every caller handles its absence.
• bench.py runs the history benchmark.

Benchmark (2026-09-28, offline, PR titles standing in for issues)

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.

Status

• Tested on real repos (Flask, pytest, Ghostty): policy, brief, claim --title, setup, check, bench, mcp.
• Tested with realistic fake GitHub data, but not yet against the live API (it was blocked in the build environment): find, claim <url>, review <url>, record, and the brief review quotes. Run them with a token before relying on them.
• Tested on temporary git repos: agent-rules (git status stays clean, the guard blocks gh pr create, the commit-msg hook enforces sign-off and the trailer), check --verify-test, tone, policy radar v2.
• Tests: python3 -m unittest discover -s tests (37 tests).

Publishing (when ready)

• PyPI: python -m build && twine upload dist/* (version 0.2.0 in pyproject.toml).
• MCP registry: server.json describes the package as io.github.adityatiwari101104/contribos; the mcp-name comment at the top of this README lets the registry verify the PyPI package. Check server.json against the current registry schema before publishing.