Overview

Provefab turns labelled GitHub issues into pull requests that arrive green, reviewed by a second model, with their evidence.

It runs on your Mac as a service. AI coding agents write the code (Claude Code, Codex or Pi, each through its own unmodified CLI, signed in with your own plan or your own API key, chosen per model), and Jev, TypeSafe’s classifier, rates each issue so that every stage runs on the cheapest model that can do it: your plans first, then your API keys by price, with prices updated daily. Everything that decides an outcome is deterministic Rust: the checks, the commit, the push and the pull request.

issue labelled `provefab`
  -> Jev classification (kind, difficulty, scope, planning depth, review risk)
  -> cheapest capable model per stage
  -> plan (read-only) -> implement (every tool call filtered by the guard)
  -> your repository's checks (your commands: fmt, lint, tests...)
  -> review by a different model provider
  -> Provefab commits and pushes, opens the PR, comments on the issue

Provefab keeps a local record of what each change observed, claimed and decided, exportable as JSON Lines.

Changes that touch CI, dependencies, migrations, infrastructure, secret-looking files or paths you name get stricter review: extra checks, a frontier reviewer from another provider when one is configured, a Risk section in the PR and a label on the issue (see Configuration).

The pull request then waits for your click. Optionally set post_merge_checks per repository: after a Provefab PR merges, Provefab runs your commands on the merged commit; on failure it can open a human-reviewed revert PR (unless a later commit already fixed it), but only when the reverted tree passes the same checks. It never merges a revert automatically. This checks repository commands, not deployed production health. Provefab Pro adds a second reviewer on another model, merge policies (auto-merge small, tested changes under fail-closed conditions), cost reports per repository and model, and reviewer calibration reports; it is not in this repository.

Quick start

Requirements: macOS, git and gh (signed in with gh auth login), and at least one worker: claude (Claude Code) or codex (Codex CLI).

# 1. Install the binary (it embeds the worker plugins), either way:
#    a. signed and notarized build, no Rust needed: download
#       provefab-<version>-macos-universal.zip from the Releases page, unzip, then
sudo install -m 755 provefab /usr/local/bin/provefab
#    b. from source, with Rust 1.96 or newer:
cargo install --git https://github.com/provefab/provefab --tag v0.2.1 --locked provefab

# 2. Sign the workers in, once, in Provefab's own config directories.
provefab login claude        # Claude plan login, in ~/.provefab/claude
provefab login codex         # ChatGPT plan login, in ~/.provefab/codex, and trust for the guard hook
# ...or your own API keys, for models with auth = "api_key" (see docs/guide/configuration.md):
provefab login claude --api-key
provefab login codex --api-key

# 3. Jev (TypeSafe) key, in the macOS Keychain. Without a key, Provefab runs
#    with cautious defaults.
security add-generic-password -s provefab-typesafe -a provefab -w <your-key>

# 4. Configure (see provefab.example.toml), then check.
mkdir -p ~/.provefab && cp provefab.example.toml ~/.provefab/provefab.toml
$EDITOR ~/.provefab/provefab.toml
provefab doctor

# 5. Try it without changing anything: classify and route the open issues.
provefab run --dry-run

# 6. Start the service (starts at login, restarts by itself).
provefab service install --workers 1

Then put the provefab label on an issue. Provefab picks it up at its next poll (every 3 minutes by default). Read an issue before you label it: the label is what authorizes agents to spend time on its text (see Security).

Day to day

To…	Run
see every task and why it is in its state	provefab status
see everything about one task (routing, stages, checks, plan, reviews)	provefab log <id>
queue an issue by hand, or restart a stopped task	provefab add <issue-url>
check tools, logins, Jev and repositories	provefab doctor
measure: PRs opened, merged (automatically or by hand), reviewers	provefab stats
export the record as JSON Lines	provefab export
delete old records	provefab prune --before YYYY-MM-DD --yes
see whether the service runs	provefab service status
follow the service live	tail -f ~/.provefab/logs/run.log
stop the service	provefab service uninstall

Provefab talks to you on GitHub, in issue comments that always start with Posted by Provefab. Labels track progress:

Label	Meaning
provefab	to do (you set it: it is the authorization)
provefab:needs-info	Provefab asked a question; answer in a comment
provefab:in-pr	a pull request is open
provefab:merged	the pull request was merged
provefab:failed	Provefab stopped; its comment says why
provefab:risk-<category>	the change touches that risk category