Contribos

io.github.adityatiwari101104v0.2.1更新於 Oct 3, 2026

Help open-source contributors earn maintainer trust: repo rules, briefs, and pre-submit checks.

已驗證STDIO僅桌面Developer ToolsKnowledge & Memory

概覽

AI 產生的概覽

為助理提供九個工具，用來研究開源儲存庫、草擬貢獻提案，並在送出前預檢拉取請求。

功能
ContribOS 提供九個 MCP 工具（policy、brief、setup、diagnose、check、review、find、claim、tone），可讀取儲存庫的貢獻規則、AI 政策、CI 設定和過往合併紀錄。它會排序應閱讀的檔案、草擬 issue 提案和審查回覆、檢查語氣與 AI 揭露尾註，並可用有變更和無變更兩種方式執行測試。它本身不會建立 PR、張貼留言或認領 issue。
適用情境
適合要向不熟悉的儲存庫送出拉取請求的貢獻者，或需要儲存庫專屬規則與送出前檢查的編碼助理。當你想要有證據支撐的檔案定位、過往 PR 先例，以及在維護者看到之前先審閱你的說明時，它很有用。
執行需求
透過 pip 安裝的本機 Python 3.10+ 套件，以及 git。find、從 issue URL 使用 claim 或 brief、review 和 record 需要 GITHUB_TOKEN。選用的 AI 摘要使用 CONTRIBOS_LLM 搭配 ANTHROPIC_API_KEY 或 OPENAI_API_KEY，以及 CONTRIBOS_MODEL。快取位於 ~/.cache/contribos，可透過 CONTRIBOS_CACHE 設定。
安裝前請注意
GITHUB_TOKEN 會授予對你 GitHub 帳號的存取權，請謹慎限定其範圍。設定 CONTRIBOS_LLM 後，選用的 AI 摘要會把已收集的證據傳送給 Anthropic 或 OpenAI。此工具會寫入本機檔案，例如 SKILL.md、鉤子和 HTML 紀錄，並將儲存庫複製到快取中。它不會建立 PR 或張貼留言，這些動作仍由你完成。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Contribos，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

ContribOS

[PyPI version] [Downloads] [License: MIT] [Python versions] [Dependencies]

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.

The journey

StepCommandWhat you get
Findcontribos find --lang python --topic webOpen 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
Rulescontribos policy owner/repoThe repo's AI policy, disclosure format (Assisted-by: and similar trailers), vouch gate, "no AI on good first issues", issue-first and claim-first norms, tests, changelog, DCO/CLA, style tools and activity, each quoted with file:line. --json gives the same rules in a form agents can read
Proposecontribos claim <issue-url>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
Tonecontribos tone comment.md --kind commentFlags machine-written tells (delve, buzzwords, assistant openers, filler), length, a missing question and leftover placeholders in anything you're about to post
Agent rulescontribos agent-rules . --ai "Claude Code"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
Setupcontribos setup owner/repoExact steps taken from the repo's CI and contributing guide: runtime version, install, services, env vars, test and lint commands
Diagnosecontribos setup --diagnose output.txtWhat 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)
Understandcontribos brief <issue-url>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 --llm for a plain-words summary that is grounded in the evidence
Provecontribos check --explain explain.md --verify-test "pytest tests/test_x.py" --issue 123 --ai "Claude Code: drafted the test" --pr-draft pr.mdPre-submit review: scope versus similar past changes, tests, changelog, sign-off, debug leftovers, AI policy and disclosure trailers, competing PRs for the same issue. --verify-test runs your test with the fix and again with your source files swapped back to the base version, so you can show it fails without your change. It checks that your explanation covers every changed file and states what you're unsure of, then drafts the PR: what and why, how you verified it, what you're unsure about, related past changes, AI assistance
Respondcontribos review <pr-url> --path .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
Growcontribos record <github-user> --html me.htmlA public, linkable record: merged PRs, change requests, whether you answered every review comment, whether you explained your change and disclosed AI use
Agentscontribos mcpNine 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: claude mcp add contribos -- python -m contribos mcp

Install

sh
pip install contribos     # Python 3.10+, git. Zero external 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)

RepoBrief hit@5Grep-only hit@5
pallets/flask (30 PRs)0.770.73
pytest-dev/pytest (30 PRs)0.870.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.

Status

  • 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 on maximilianfeix/proxy-scraper and brekkylab/backlot), claim <url> (drafted pre-coding proposals with past similar PRs and file targets), and record (verified public merged PR portfolio for @adityatiwari101104).
  • 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: python -m unittest discover -s tests (40 tests, CI matrix on Linux, macOS, and Windows).

Releasing

To publish a new release to PyPI:

sh
python -m buildtwine upload dist/*git tag v<version>git push origin v<version>

來源：README.md，提交 9ddb5f4

工具

0
工具後設資料尚未被收錄。

版本歷史

1
  1. v0.2.1最新Oct 3, 2026