Code review
Review a diff, a GitHub pull request or a GitLab merge request read-only with venom review or /review, post the findings, watch a repository, and have the agent review itself before it opens a pull request.
venom review reads a change and reports findings ranked blocker, major, minor and nit, each with file:line, the problem, why it matters and a fix. It runs in read-only sessions: nothing is edited, and nothing but the model is contacted (plus GitHub or GitLab when you ask it to post).
Examples
venom review # working tree vs HEAD, staged and unstaged, plus untracked files
venom review --staged # only what is staged, before a commit
venom review --base main # what this branch adds since its merge base with main
venom review --security --gear eco # a security review on a cheap gear
venom review --pr 128 --post # review a GitHub pull request and post the review
venom review --json > review.json # the venom.review/v1 reportIn the TUI, /review takes the same target flags and adds the report to the conversation, so "fix the blockers" can follow. /security-review is /review --security.
Targets and options
| Flag | Default | What it does |
|---|---|---|
| (none) | The working tree vs HEAD, plus untracked files. | |
--staged |
Only what is staged. | |
--unstaged |
Only what is not staged, plus untracked files. | |
--file <path> |
Only this file or directory of the diff (repeatable). | |
--base <ref> |
What HEAD adds since its merge base with <ref>. |
|
--commit <sha> |
One commit. | |
<from>..<to> |
A commit range; <from>...<to> diffs from their merge base. |
|
--security |
off | Focus on injection, authorization, secrets, path traversal, SSRF, deserialization, crypto, sandbox escapes and supply chain. |
--fail-on <sev> |
blocker |
Exit 1 for a finding at least this severe: blocker, major, minor or nit. |
--json |
off | Print the venom.review/v1 report on stdout. |
--model <id> |
the gear's, else VENOM_MODEL, else venom-default |
The reviewer model. |
--gear <name> |
review.gear |
Review on a gear's main model and route profile. |
--max-usd <n> |
none | Stop once the review's requests cost this much at list price (exit 2, nothing posted). |
--break[=<model>] |
off | A second read-only session tries to break the change with a concrete failing input, adding findings tagged breaker (never above major). Only for changes at risk tier medium or above (--break-min-tier). |
instructions… |
Extra focus, such as focus on error handling. |
Every review prints what it used: models, tokens and the list-price cost.
Exit status: 0 no blockers, 1 at least one blocker (or the --fail-on severity), 2 the review could not run or posting failed.
Pull requests and merge requests
venom review --pr 128 [--repo owner/name] [--post]
venom review --mr 42 [--repo group/project] [--post]
venom review --watch owner/name --post [--interval 300] [--once]| Flag | What it does |
|---|---|
--pr <n|url> |
Fetches the PR's head and base with git and reviews what the PR adds. The repository is the URL's, --repo's, or the origin remote's. |
--mr <n|url> |
The same for a GitLab merge request (also --pr with an MR URL or group/project!n). |
--post |
Posts the result. GitHub: one review with inline comments on the diff's lines, REQUEST_CHANGES only for a blocker, replacing venom's previous review. GitLab: a summary note plus inline discussions; with a blocker the summary is an unresolved thread. Nothing is posted without it. |
--watch <repo> |
Polls the open PRs or MRs and reviews each new head commit. Which heads were reviewed is kept in ~/.venom. |
--interval <s> |
Seconds between polls (default 300). |
--once |
Poll once and exit (for cron or CI). |
Tokens: GITHUB_TOKEN, GH_TOKEN, else gh auth token; GITHUB_API_URL for GitHub Enterprise. For GitLab: GITLAB_TOKEN, CI_JOB_TOKEN, else glab's login; the API is GITLAB_API_URL, else CI_API_V4_URL, else the MR URL's host, else https://gitlab.com/api/v4.
Nothing from the pull request runs: the reviewer only reads files and runs read-only commands, with project toolchains denied and secret-named variables removed from its shell. To run reviews on every pull request in CI, use the review action.
A git hook
venom review install-hook # a pre-commit hook that reviews on the eco gear
venom review install-hook --pre-push # on push instead
venom review install-hook --uninstallThe hook stops only on blockers. Skip it once with VENOM_SKIP_REVIEW=1.
Other subcommands
venom review retest <report.json> <finding-id> [--fix]re-checks one finding from a saved report.venom review --evidence [--base <ref>] [--pr <n>]opens on the evidence bundle (risk, tests, deltas, invariants) with keys to approve (a), send to the model reviewer (v) or request changes (r). No model runs until you pressv.
Self-review before a pull request
When the agent runs gh pr create (or glab mr create), venom first reviews what the branch adds on its base with the same engine. With a blocker or major finding the command is not run: the agent gets the findings, fixes the real ones, dismisses the rest with a reason, and runs the command again with a ## Self-review section in the body. A clean review, a review that cannot run (no model, over max_usd, ten minutes) and the retry after the last round all let the command through, so it never blocks for good. Skip it for one run with venom --no-self-review.
Settings
review:
gear: eco
model: venom-smart
before_pr: true
rounds: 1
max_usd: 2| Key | Type | Default | What it does |
|---|---|---|---|
review.gear |
string | none | The gear venom review runs on when no --model or --gear is given. |
review.model |
string | the gear's smart tier | The self-review's model; also venom review's when nothing else is set. |
review.before_pr |
boolean | true |
Self-review before the agent opens a pull request. |
review.rounds |
integer 0 to 5 | 1 |
How many times the pull request may be held back for fixes. 0 is the same as before_pr: false. |
review.max_usd |
number | 2 |
Stop one self-review at this cost. |
A project file's model, before_pr and max_usd apply only once the project is trusted.
Related
- The review action: a pull request review bot for GitHub Actions and GitLab CI.
- Spec to pull requests reviews each slice before opening its PR.