PR-AF: an open-source agentic code reviewer that grounds findings in code evidence

What PR-AF reviews that a diff summarizer does not

Most review bots read a diff and produce prose. PR-AF's README draws the line differently: it says the tool is built for deep code review, not shallow diff summaries, and the pipeline it describes is aimed at a specific failure mode of diff-only reviewers, which is a plausible-sounding comment that turns out to be wrong when you open the file.

The target user is a team that already runs its own infrastructure and is uncomfortable shipping source diffs to a hosted reviewer. The README lists self-hosted API as a strength: run locally with Docker, trigger reviews by CLI, curl, CI, or other agents. That framing points at platform teams and security-conscious engineering groups rather than individual developers who want a one-click app install.

The second group the README addresses is cost-sensitive. It claims PR-AF is about 10x cheaper per review than closed-source tools, and it presents model choice as a dial: DeepSeek-class models for routine PRs, GLM-5.2 for open-model reviews, Opus-class frontier models for major PRs. Whether that dial is worth the operational cost of running a control plane is the real adoption question, and the README does not answer it.

The seven-phase pipeline and where evidence grounding sits

PR-AF does not run a fixed script. According to the README, it structurally morphs its own execution graph based on the topology of the incoming pull request. The Mermaid diagram in the README lays out the phases in order: intake triage, topological anatomy mapping, then three lens generators (semantic, mechanical, systemic) that feed a dimension deduplication and compilation step.

That compilation step is where the design gets interesting. Instead of running one reviewer over the whole diff, the pipeline spawns N reviewer threads, one per compiled dimension. The diagram names examples: state mutation, API boundaries, and dynamic context. Each thread then passes through a programmatic AST extraction engine, which the README describes as pulling exact caller snippets and import context from the repository.

The next stage is the one that differentiates PR-AF from a prompt-only reviewer. An evidence verification layer prunes unsubstantiated claims, and a falsifiability gate follows. In the README's words, if the system flags a missing validation check, it does not immediately accept it; it pulls caller snippets and import context, then verifies whether the finding is grounded in the code before it reaches the final review.

After that, findings are clustered by file topology, shared imports, and tag overlap into compound clusters, and a compound vulnerability synthesis step evaluates whether isolated findings combine into something worse. A coverage depth gate can send the pipeline back to intake triage if blind spots are detected. The output is synthesized GitHub annotations. The JSON example in the README shows what a finding carries: severity, title, file, line, body, suggestion, evidence, and a compound_risk field that references another finding by number.

Installing PR-AF and running one review

There is no pip install path documented in the README. The repository ships a docker-compose.yml that starts two services: the AgentField control plane on port 8080 and the pr-af agent on port 8004. The compose file reads several environment variables from a .env file, and .env.example lists them. Copy the example file first and fill in at minimum OPENROUTER_API_KEY, since the default model is served through OpenRouter.

cp .env.example .env
# edit .env: set OPENROUTER_API_KEY, and GH_TOKEN if you want comments posted
docker compose up -d

The compose file defaults PR_AF_PROVIDER to aforge and PR_AF_MODEL to deepseek/deepseek-v4-flash-0731. The pr-af service waits on the agentfield service with condition: service_started, and it exposes a healthcheck against http://localhost:8004/health. If that healthcheck never goes green, the agent container is the place to look, not the control plane.

Once both containers are up, the README's one-call example triggers a review through the af CLI. The README states this requires af version 0.1.87 or later.

af call pr-af.review --in '{"pr_url": "https://github.com/owner/repo/pull/123"}'

If you would rather not install the CLI, the README gives a raw HTTP equivalent against the control plane. Note that the CLI example and the curl example use different JSON shapes: the CLI takes an --in object with pr_url at the top level, while the HTTP endpoint wraps it in an input key.

curl -X POST http://localhost:8080/api/v1/execute/async/pr-af.review \
  -H "Content-Type: application/json" \
  -d '{"input": {"pr_url": "https://github.com/owner/repo/pull/123"}}'

The response shape shown in the README includes total_findings, by_severity counts, a findings array, and review_dimensions. Each finding carries an evidence string. Read those before you trust a severity label.

Where PR-AF gets in the way

The dependency chain is the first real constraint. PR-AF is not a standalone binary; it is a node on an AgentField control plane. docker-compose.yml starts agentfield/control-plane:latest with AGENTFIELD_STORAGE_MODE=local and AF_MODE=dev, which is a development configuration. The README does not document what changes for a production deployment, and it does not describe how the control plane's state is backed up or migrated.

Version skew is the second constraint, and the repository makes it visible. The README says the af CLI must be at least 0.1.87. pyproject.toml requires agentfield>=0.1.130. The Dockerfile pins the AForge CLI to ARG AFORGE_VERSION=v0.1.0. Those are three independent version pins across three components, and a mismatch between them is a plausible source of a review that silently produces nothing.

The provider abstraction is the third. .env.example sets PR_AF_PROVIDER=aforge and notes that PR_AF_PROVIDER=opencode rolls back to the other harness. It also carries a comment that the pinned Python SDK always runs exec, meaning the AGENTFIELD_AFORGE_COMMAND setting is read by a Go adapter, not by the Python path. The repository has both a go/ directory and a src/ directory, so there are two implementations in play, and the README does not explain which one runs in a given deployment.

Cost and duration caps are configurable, not automatic. .env.example sets PR_AF_MAX_COST_USD=2.0 and PR_AF_MAX_DURATION_SECONDS=3600, with PR_AF_MAX_TURNS=50 and retry settings. If a review hits those ceilings, the README does not say what the caller receives. There is also a documented idle watchdog, AGENTFIELD_HARNESS_IDLE_SECONDS=360, with a comment that harness CLIs in JSON mode emit events only at completion boundaries, so long single completions look silent. That is an honest note about a real failure mode, and it is buried in an env file rather than in the README.

PR-AF against PR-Agent and hosted reviewers

The closest open-source alternative a reader will encounter is PR-Agent. The difference in approach is architectural rather than cosmetic. PR-Agent is typically invoked as a CI step or a bot command against a diff, with the model doing the reasoning and the surrounding tooling handling the GitHub plumbing. PR-AF inverts that: the pipeline compiles review dimensions from the PR's structure, spawns a reviewer per dimension, and routes every candidate finding through an AST extraction step and a verification gate before it can appear in the output.

That buys evidence grounding and compound-risk clustering. It costs a control plane, a workspace volume, and a harness binary. PR-Agent's model is easier to reason about operationally because there is less machinery between the trigger and the comment.

The hosted comparison in the README is narrower than it looks. PR-AF claims 0.706 golden recall on the 38 runnable Martian Code-Review-Bench PRs, ahead of cubic-v2 and every qodo, coderabbit, greptile, copilot, and devin variant in that snapshot, across 42 compared tools. It also claims 595 independently valid findings, roughly 3x more than the leading commercial tools in the adjusted comparison. Those are the project's own reported numbers with a public reproduction package under benchmark/martian-code-review-bench, which is more than most vendors offer, but they are still the project's numbers on a 38-PR set. Recall on known bugs is not the same as precision, and the README does not report a false-positive rate.

Licence, maintenance and the cost of staying current

The README badge declares Apache 2.0, and pyproject.toml sets license = "Apache-2.0". The repository's LICENSE file was not available to inspect, so treat the badge and the package metadata as the claim and confirm the file itself before you rely on it. Apache 2.0 carries an explicit patent grant and requires attribution and notice retention, which matters if you fork the pipeline or redistribute the container image. This is a description of what the licence generally does, not legal advice.

The last push to the default branch was on 2026-08-21. The repository is not archived. There were no releases retrieved, so there is no versioned artifact to pin against; the compose file pulls agentfield/control-plane:latest, which means an upgrade can change the control plane under you without a PR-AF commit. The Dockerfile's AForge stage pulls a released CLI from agentfield.ai/downloads/aforge and verifies it against checksums.txt, hashing the decompressed binary. That is a sensible supply-chain step, and it is also one more moving part that can fail at build time if the download host changes layout.

Upgrade cost is therefore not a single pip bump. It is the af CLI version, the agentfield Python package, the control plane image tag, and the AForge CLI version, plus whatever the harness binaries do. The README does not document a rollback procedure for any of them.

Editorial conclusion

Adopt PR-AF if you already run AgentField or are willing to run the control plane in docker-compose.yml, you have an OpenRouter key, and you want review findings that cite extracted caller snippets rather than free-form model prose. Do not adopt it if you need a single-binary GitHub Action, a documented rollback path, or a licence file you can point at today; the README badge says Apache 2.0 but the repository's LICENSE file was not available to inspect. Verify first that af is at least 0.1.87 and that the agentfield control plane answers on port 8080, then run one review against a throwaway PR and read the evidence field on every finding before you wire it into a required status check.

Frequently asked questions

Official sources

1. Agent-Field/pr-af on GitHub
2. Issues
3. Project website
4. README