ContribAI

A maintainer-governed admission and evidence layer for AI-assisted open source contributions.

Website · Deploy website · Why ContribAI · Safety model · Quick start · Consent protocol · Architecture

ContribAI analyzes repositories and prepares small, reviewable changes. It does not treat a public repository as permission to write. Submission is a separate capability that must be enabled by the operator, authorized by the target maintainer, bounded by policy, reviewed by a human, and published as a draft pull request with an evidence receipt.

The project website is a dependency-free introduction and read-only onboarding path. It is informational only and exposes no ContribAI runtime capability.

Deploy the public website

The Vercel deployment serves only the static files under site/. It needs no environment variables, tokens, functions, or access to the credential-bearing Rust runtime. Project maintainers should follow the existing-repository deployment guide instead of cloning the repository through the button.

public code ≠ permission to submit
generation ≠ admission
passing checks ≠ maintainer approval

Why ContribAI

AI can make code generation cheap while making review expensive. The failure mode is not merely bad code; it is uninvited work that transfers verification cost to maintainers. ContribAI is built around the opposite incentive:

• Maintainer intent first. A repository manifest or maintainer-controlled issue label is required before an external proposal can be submitted.
• Read-only by default. Discovery, analysis, scheduling, patrol, and MCP start without external write capability.
• Evidence over confidence. Every admitted proposal records consent source, base revision, changed paths, changed-line budget, deterministic change fingerprint, and validation checks.
• Bounded proposals. Protected governance files, unapproved paths, expired permits, oversized changes, failed checks, and missing base revisions fail closed.
• Human accountability. The CLI requires an explicit review decision. Pull requests are always drafts. ContribAI never signs a CLA or merges code.

This is a tool for maintainers and accountable contributors—not a contribution-farming bot.

Safety model

An external draft can be created only when every gate passes:

operator --submit
      │
      ▼
repository manifest OR maintainer issue label
      │
      ▼
24-hour ContributionPermit bound to repository + base SHA
      │
      ▼
scope, protected-path, size, risk, quality, and validation checks
      │
      ▼
interactive human review
      │
      ▼
draft PR + EvidenceCapsule

Important invariants:

See the threat model and the consent protocol for precise boundaries.

Quick start

Install a release

curl -fsSL https://raw.githubusercontent.com/tang-vu/ContribAI/main/install.sh | bash

On Windows PowerShell:

irm https://raw.githubusercontent.com/tang-vu/ContribAI/main/install.ps1 | iex

The installers select the latest published stable release and verify its checksum. Set CONTRIBAI_VERSION to an exact tag (for example, v6.10.0) to pin a release. See installation options for platform commands. The isolated install path is smoke-tested against the published binary on Linux, macOS, and Windows for every release.

Build from source

Requirements: Rust stable and Git. Credentials are not needed for the offline proof.

git clone https://github.com/tang-vu/ContribAI.git
cd ContribAI
cargo install --path crates/contribai-rs --locked

Prove the boundary offline

Run the production consent, admission, and evidence path without config, credentials, network access, or external writes:

contribai demo
contribai demo --json
contribai demo --manifest examples/quickstart-repository/.github/contribai.yml --json

The demo also probes a protected workflow path and confirms that it is denied. Continue with the five-minute walkthrough and inspect the bundled quickstart repository.

Connect locally

Configure secrets through environment variables instead of committing them:

export GITHUB_TOKEN="..."
export GEMINI_API_KEY="..."       # or OPENAI_API_KEY / ANTHROPIC_API_KEY
contribai init
contribai doctor

Start safely

These commands do not submit anything:

contribai analyze https://github.com/owner/repo
contribai target https://github.com/owner/repo
contribai run
contribai patrol
contribai mcp-server

To run the v7 contribution lifecycle against a maintainer-authorized issue:

contribai contribute owner/repo --issue 123 --dry-run
contribai contribute owner/repo --issue 123
contribai runs
contribai inspect-run <run-id>
contribai conformance

--dry-run executes through evidence packaging and stops: no review prompt, no external write. conformance runs the offline safety-invariant suite. runs and inspect-run are read-only.

To request an admitted draft proposal:

contribai target https://github.com/owner/repo --submit
contribai solve https://github.com/owner/repo --submit
contribai contribute owner/repo --issue 123 --submit

--submit is necessary but not sufficient. The repository must opt in, every check must pass, and the local operator must approve the exact evidence-bearing change interactively. The review renders every regular and test change without truncation; current consent is checked again before writing.

Consent protocol

Maintainers can opt in repository-wide with .github/contribai.yml:

schema_version: 1
enabled: true
max_files: 3
max_changed_lines: 120
allowed_paths: src/**, tests/**

The uppercase marker paths remain supported for compatibility with the experimental v1 protocol.

Operators can inspect the gate without invoking an LLM or writing to GitHub:

contribai consent-check owner/repo
contribai consent-check owner/repo --json --require-consent

For narrower approval, apply one of these labels to an issue:

• contribai-approved (canonical)
• agent-ready or ai-contribution-approved (compatibility aliases)

Issue approval is scoped to that issue. Repository consent is still bounded by its path and size budgets. Missing, malformed, or disabled consent is a denial.

Evidence Capsule

Each admitted draft includes a compact receipt such as:

Permit:               1d28…
Consent:              maintainer label `agent-ready` on #42
Base revision:         7a93…
Change fingerprint:    c441…
Scope:                 2 files / 37 changed lines
Evidence expires:      2026-08-11T08:00:00Z
Submission mode:       draft only
Checks:                admission, quality, risk, validation

The capsule makes the proposal reproducible and reviewable. The write boundary rejects expired, failed, cross-repository, scope-mismatched, or fingerprint-mismatched capsules and revalidates live maintainer consent. It remains a local audit receipt, not a substitute for CI, code review, provenance attestation, or maintainer judgment.

ContribAI attempts to append every terminal admission decision to the local audit ledger. Records contain the candidate fingerprint, permit/base SHA when available, scope, checks, decision stage, and reason—never generated file contents. Each record's SHA-256 receipt binds the preceding receipt, so accidental edits or broken ordering are detectable when the complete local chain is verified:

contribai admissions
contribai admissions --repository owner/repo --decision blocked
contribai admissions --json

The hash chain is a local integrity check, not a signature or remote attestation. An approved submission fails closed if its audit decision cannot be persisted. Each append verifies the retained history in the same write transaction; corrupted history blocks new receipts. See audit recovery for preserving and restoring evidence.

Capabilities

• Tree-sitter analysis for 13 languages, with additional fallback language mappings
• Security, correctness, performance, testing, documenta