prxref

Fast automated AI code review for Bitbucket, GitLab, and GitHub — Cloud and self-hosted.

prxref inspects pull and merge requests across the three major code hosting forges in sub-minute review cycles. It parses unified diffs, partitions changes into risk-ranked chunks, gives each worker the dependency pins and out-of-hunk definitions its chunk references when the forge can serve file content, fans out parallel single-shot LLM reviews across a cheap-first model fallback chain, filters findings through deterministic quality gates, and publishes inline comments alongside an executive summary.

                  ┌──────────────────────┐
                  │    Pull / MR URL     │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │     detect_forge     │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │    Forge Adapter     │
                  │ (BB / GitHub / GL)   │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │     Unified Diff     │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │ Risk-Ranked Chunking │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │ Parallel LLM Workers │
                  │  (Fallback Chain)    │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │     Quality Gate     │
                  │ Line Align / Dedup   │
                  └──────────┬───────────┘
                             │
                             ▼
                  ┌──────────────────────┐
                  │ Post Inline Comments │
                  │     + Summary        │
                  └──────────────────────┘

Deterministic Checks and Quality Passes

Not every finding comes from a model, and no finding posts unfiltered. prxref computes one class of finding directly from the parsed diff — the release-shaped-PR check — and then runs every finding, model-authored or not, through eleven deterministic passes: location validation, package.json claim checks, line alignment, thread dedup, settled-thread suppression, severity consistency, the removal-claim check, the hedge gate, the quality gate, sweep dedup, and the containment note. A filtered finding is never discarded silently — it is kept with a drop_reason for the run log, and visible in a --no-post dry run or under --format json.

The passes, the checks, every drop_reason string, and which of them have a knob: docs/quality.md.

Quickstart

Run reviews instantly without local installation using uvx, or install the CLI globally:

# Run one-shot review via uvx
uvx prxref review --pr-url https://github.com/org/repo/pull/123

# Or install tool globally
uv tool install prxref
prxref review --pr-url https://github.com/org/repo/pull/123

# Or install straight from source (works before the first PyPI release)
uv tool install git+https://github.com/sblattj/prxref

Review Any Forge

Pass any PR or MR URL directly. Forge type, repository namespace, and pull request ID are detected automatically:

# Bitbucket Cloud
prxref review --pr-url https://bitbucket.org/workspace/repo/pull-requests/42

# Bitbucket Server / Data Center (self-hosted, any host, with or without a deployment context path)
prxref review --pr-url https://bitbucket.corp.example/projects/PLAT/repos/api/pull-requests/42

# ...including a plain-HTTP deployment, e.g. the standalone install's default port
prxref review --pr-url http://bitbucket.internal:7990/projects/PLAT/repos/api/pull-requests/42

# GitHub & GitHub Enterprise
prxref review --pr-url https://github.com/owner/repository/pull/108

# GitLab & Self-Hosted GitLab (including nested subgroups)
prxref review --pr-url https://gitlab.com/group/subgroup/project/-/merge_requests/15

Supported hosts. Every forge is supported on any host. GitHub Enterprise Server and self-hosted GitLab share one adapter each with their SaaS products, which speak the same REST API at a different base URL. Bitbucket does not: Server / Data Center speaks /rest/api/1.0 against different resource shapes, so it is a separate adapter selected automatically from the URL — PRXREF_BITBUCKET_SERVER_TOKEN for Data Center, PRXREF_BITBUCKET_TOKEN for Cloud. See docs/forges.md.

LLM Configuration

prxref operates without direct cloud provider SDK keys (no Anthropic API keys). It ships with no default endpoint and no default model chain: point it at any OpenAI-compatible /chat/completions server (OpenRouter, Together, Groq, vLLM, Ollama, a self-hosted gateway), or install the optional litellm extra. PRXREF_LLM_BASE_URL and PRXREF_LLM_MODELS are required — leaving either unset exits 2 with an error naming the variable.

# Default backend: plain HTTP to any OpenAI-compatible endpoint
export PRXREF_LLM_BACKEND=openai-compat        # aliases: ferry, http
export PRXREF_LLM_BASE_URL="https://openrouter.ai/api/v1"
export PRXREF_LLM_API_KEY="$OPENROUTER_API_KEY"
export PRXREF_LLM_MODELS="z-ai/glm-5.3-flash"
export PRXREF_LLM_REASONING_EFFORT=low
export PRXREF_LLM_MAX_TOKENS=4096              # raise this if you raise the effort

# Optional: in-process litellm extra
# pip install 'prxref[litellm]'
export PRXREF_LLM_BACKEND=litellm
export PRXREF_LLM_MODELS="openrouter/meta-llama/llama-3.3-70b-instruct,bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0"

On a reasoning model the hidden reasoning trace draws from the same completion budget as the answer, so turning PRXREF_LLM_REASONING_EFFORT up makes truncation more likely. A truncated chunk is counted as failed and the posted summary names the reason and the variable to raise; see Reasoning models and the token budget.

Temperature 0.0 and an optional PRXREF_LLM_SEED are sent on every call, but neither makes a review bit-reproducible — provider fingerprints, load-balanced backends, and gateways that ignore seed all still vary the model's output. Everything downstream of the model is deterministic: findings are ordered by (file, line, title) and the caps break ties by content, and the run record's sampling field reports which knobs were in force. See Determinism.

See docs/llm.md for architecture, failover behavior, and backend setup, and docs/env-vars.md for tuning the confidence floor and finding caps to your team.

Forge Authentication

Configure the authentication token matching your forge:

See docs/env-vars.md for the full configuration reference, docs/forges.md for forge specifics, docs/quality.md for the deterministic checks and every drop reason, and docs/systemic-sweep.md for the whole-PR sweep's digest classes.

Webhook Server

Run prxref as a persistent daemon to handle webhook events from GitHub, Bitbucket, and GitLab:

prxref serve --port 8080 --host 0.0.0.0

The service exposes:

• POST /webhook — verifies HMAC or token signatures per forge, enqueues incoming PR events, and responds immediately with 202 Accepted. A background worker processes reviews serially.
• GET /health — liveness probe returning {"ok": true}.

CLI Flags

• --pr-url URL — full web URL of the PR or MR (required for review).
• --no-post — dry run; run review analysis and quality passes without writing comments to the forge. In text mode this also prints every active finding's location, title, and body, and every dropped finding with its drop reason.
• --max-chunks N — override maximum diff chunks evaluated (default 8).
• -v, --verbose — output run timing, token counts, and finding breakdowns to stdout; in text mode this also prints finding bodies and dropped findings, same as --no-post.
• --format {text,json} — output format for review (default text). json prints exactly one JSON object to stdout — verdict, findings (active first, then dropped, each with file, line, severity, confidence, title, body, drop_reason), chunk_count, chunks_reviewed, chunks_failed, elapsed_ms, input_tokens, output_tokens, posted, and sampling (the temperature, seed, and models the run had in force — every review result carries it).

Exit Codes

prxref is an advisor, never a gate. Its exit code says whether prxref was configured correctly, not whether your code is good.

$ prxref review --pr-url https://github.com/org/repo/pull/1 --max-chunks 0
configuration error: --max-chunks: must be a finite number greater than 0, got 0

PRXREF_FAIL_ON is the one opt-out of the advisory contract, and its default never is the doctrine above, unchanged. Setting it to error or any turns the reviewer into a merge gate — failing a build on a finding turns a probabilistic reviewer into a gate, and the first false positive teaches a team to bypass the gate, so think hard before you set it. Read the verdict from the posted summary, which also carries a partial-review banner when some chunks did not make it. Do not build a security control on the exit code. The webhook daemon has no exit code and is unaffected.