pr-review-agent
A locally-hosted LLM pull request reviewer that cannot overspend and cannot be summoned by a stranger.
A single Python asyncio daemon with a SQLite store, running on a private host. It polls on pull requests of a GitHub repository for exactly two events:
- a freshly opened pull request whose author is pre-approved;
- a comment containing
@claudewhose commenter is pre-approved.
and performs code review using Claude CLI and posts review comments on the pull request.
🚀 Quickstart
Requires: Python 3.10 – 3.14 and python virtualenv. Download latest release.
python -m venv .venv
source .venv/bin/activate
# download the latest release
pip install pr_review_agent-<version>-py3-none-any.whl
pr-review-agent config generate # writes ./config.yaml
# update config; `config generate --full` writes the commented template
pr-review-agent config validate
# get GitHub PAT with read and write permissions on pull requests
GITHUB_TOKEN=xxxx pr-review-agent host check # can this host reach it all?
GITHUB_TOKEN=xxxx pr-review-agent daemon start # reads ./config.yaml
GITHUB_TOKEN=xxxx pr-review-agent daemon start --config /etc/pr-review-agent/config.yaml
Installing the package puts pr-review-agent on the path. Commands follow a
pr-review-agent <noun> <verb> grammar, grouped by the setup workflow:
config → host → daemon. --config is optional: without it a command
reads config.yaml from the directory it is started in, which is also where
state.db is written.
🗂 Documentation
| Document | Answers |
|---|---|
| docs/CONFIG.md | What settings exist, what does each accept, and why are unknown keys an error? |
| docs/DESIGN.md | Why does this exist and why is it shaped like this? The four constraints, every alternative considered and rejected, the billing-mode question that is still open, and how prompt injection is handled |
| docs/ARCHITECTURE.md | What actually runs? The components, the path an event takes, the package layout, and which layer may import which |
| docs/TRIGGERS.md | What starts a review and what does not? Every reason code and its log level, what counts as a mention, the dedupe keys, and why identity is a number |
| docs/POLLER.md | How does it learn something happened without an inbound port? The three endpoints, the rate-limit arithmetic, the adaptive interval, the retry rules, and how a comment payload is mapped to a pull request |
| docs/DAEMON.md | What runs continuously, and what is it careful not to do? The cycle, the cold-start spend bound, the two watermark ordering rules, and how it shuts down |
| docs/QUEUE.md | Where does an accepted trigger wait, and what stops one review being paid for twice? Dedupe, the per-pull-request lease, why leases expire instead of renewing, and the retry bound |
| docs/STORAGE.md | What has to survive a restart, and what does a lost watermark actually cost? Why SQLite, and why a watermark only moves forward |
| docs/WORKSPACE.md | How does a pull request's code get onto disk, and why is none of it ever run? The bare mirror, the per-run worktree, the untrusted-tree hardening, and the diff-size caps |
| docs/BUDGET.md | The rolling windows and the share that guarantees human headroom, reserve-then-settle under concurrency, the degradation ladder, the circuit breaker, and what is still not built |
| docs/WORKER.md | What drains the queue? The claim-run-settle loop, what a failed run settles at and why, which failures retry and which are permanent, what a run leaves behind, the supervisor, and why not a process per review |
| docs/PUBLISHER.md | How does a review become visible, and what stops the agent approving anything? The 👀 at claim time, the live head_sha re-check, one comment per pull request, publish.dry_run, and why a failed publish never costs a second review |
| docs/ENGINE.md | How does a different coding agent plug in? The one swappable step, what an engine is given and must return, the capability record, and why every adapter is a CLI subprocess rather than an SDK |
| docs/ROADMAP.md | What is built, what is next, the acceptance checklist, and the known gaps |
| DEVELOPER.md | How do I set up, test, lint and build this? |
| CLAUDE.md | The behavioural guidelines applied to every change |
| AGENTS.md | The coding-assistant conventions |
1 maintainer
Release files for pr-review-agent 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pr_review_agent-0.16.0.tar.gz | 103.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pr_review_agent-0.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 229.7 kB
Release files / pr_review_agent-0.16.0.tar.gz
| Download URL | pr_review_agent-0.16.0.tar.gz |
|---|---|
| Size | 103.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c7f6edd58021e22ff05890af447456af368779ddb232515d4b1047b3dadebe1c
|
|
BLAKE2b-256 checksum How to use checksums |
e6deb3136031adfc946bd839727fe7fd256f962d0e15393be0227e4d17e5e09a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 19, 2026.
Transparency logRelease files / pr_review_agent-0.16.0-py3-none-any.whl
| Download URL | pr_review_agent-0.16.0-py3-none-any.whl |
|---|---|
| Size | 126.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
da4bb03d0d29486a54bbeacfa4fbc7ff92d60fc91086e873666de73b093e6189
|
|
BLAKE2b-256 checksum How to use checksums |
67e58b4929d8e0fe78f0edf60c660aba825122c4b4dd12946cad589db831d858
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 19, 2026.
Transparency log
