A lean, low-cost PR reviewer. A single agent, single pass posts high-signal findings and one
structured verdict on each pull request. It is a simplified fork of the multi-agent
ai-code-review engine — same review quality bar, a fraction of the tokens and time.
On a PR (or an @ai-review comment) it:
- Reads the PR diff (shallow checkout — no
git blame). - In one pass, finds candidates across two lenses — bugs/correctness and rule compliance
(the inlined general rules + any rules you supply via
custom_rules) — then self-critiques each candidate adversarially and drops anything it can't prove or that scores below the confidence threshold. - Posts surviving findings as inline comments (
🔴 Important/🟡 Nit, each with a confidence score) plus one top-level verdict comment. - Writes an evaluation log of every candidate (posted and dropped) to the workflow run Summary — never to the PR.
It is advisory: it never approves or blocks, and continue-on-error means it can't fail your
checks. If a run can't complete (most often an exceeded Anthropic API usage/credit limit) it posts
a sticky "AI review — not completed" comment instead of silently passing — see
Failure handling.
Original ai-code-review |
This | |
|---|---|---|
| Contexts per review | orchestrator + 3 finders + 1 judge (≈5) | 1 |
| Noise control | independent judge sub-agent | in-context self-critique gate |
git blame lens |
yes (full-depth checkout) | no (shallow checkout) |
| Rule delivery | central packs by stack | general inlined (cacheable prefix) + consumer's own custom_rules |
max_turns default |
60 | 30 |
The general ruleset is inlined as a fixed prompt prefix (identical every run) so prompt caching kicks in; all per-run values are appended at the end so the prefix stays cacheable.
- Copy
examples/caller.ymlto.github/workflows/ai-review.ymlin your repo. - Set
uses: OWNER/REPO/.github/workflows/review.yml@<sha>to this engine repo + a pinned commit. - Add the
ANTHROPIC_API_KEYsecret. - (Optional) set inputs — see below.
| input | default | purpose |
|---|---|---|
model |
claude-sonnet-4-6 |
model id passed to the action |
effort |
high |
reasoning effort: low/medium/high/xhigh/max — higher catches subtler bugs at higher token cost |
custom_rules |
"" |
your repo's rule file path(s), comma-separated, applied above the general rules |
review_scope |
diff |
diff = only changed lines; touched = also flag 🔴 pre-existing issues in touched code |
max_turns |
30 |
agent turn cap; raise for very large PRs |
delete_superseded_comments |
true |
on each run, delete the bot's inline comments from prior runs (keeps this run's) so re-reviews don't pile up; set false to keep them |
fail_on_error |
false |
fail the job when the review can't complete (e.g. usage/credit or rate limit), so branch protection can block the merge; the failure notice is posted either way — see Failure handling |
debug |
false |
verbose run log |
Secret: ANTHROPIC_API_KEY (required).
Rule precedence (highest first): REVIEW.md (consumer repo root) > custom_rules > inlined general rules.
Add synchronize to the caller's pull_request types (see examples/caller.yml)
to re-review on every push. Across re-reviews:
- the top-level verdict is one sticky comment, edited in place — not stacked (
gh pr comment --edit-last); - the bot's inline comments from prior runs are deleted each run (works with the default
GITHUB_TOKEN), leaving only the current findings — setdelete_superseded_comments: falseto keep them; - the review runs at
--effort high, needed for reliable detection of subtle correctness bugs (e.g. transaction-isolation regressions) that lower effort mis-clears.
The engine ships only a general, cross-stack ruleset (inlined). Platform- or stack-specific rules
live in your own repo: add one or more markdown rule files (e.g. .github/ai-review-rules.md)
and point custom_rules at them. They are read from the PR checkout at run time and applied above
the general rules. This keeps the engine tiny and lets each repo own exactly the rules it needs.
The review step runs with continue-on-error, so an incomplete run — most commonly an exceeded
Anthropic API usage/credit limit, or a rate limit — would otherwise leave the job green with
nothing posted, which reads as "reviewed, all clear". Instead, when the review step doesn't
succeed the engine:
- posts a sticky top-level comment ("🤖 AI review — not completed") stating that no findings were posted and the PR is not certified clean, with a best-effort likely cause read from the execution log. It's upserted by a hidden marker, so it neither clobbers a real verdict nor stacks across re-runs;
- mirrors the same notice to the run Summary.
By default the check still stays green (advisory). To make an incomplete review block merges,
set fail_on_error: true in the caller — the notice is posted first, then the job fails so branch
protection can gate on it.
The reviewer is read-only. The tool allowlist grants Bash only as gh pr view/diff/comment —
no generic shell — so it cannot build, run, install, or test the project. Task/Agent are not
granted (no sub-agents); git blame/git log are not granted (no history). A 15-minute job
timeout bounds any runaway. The runner is ephemeral with no push step.