Skip to content
Docs menu

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.

View .md

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 report

In 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 --uninstall

The 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 press v.

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.