---
title: Code review
description: 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.
section: automation
order: 70
audience: [user, operator, agent]
sources: [cli/src/review.ts, cli/src/review-pr.ts, packages/harness/src/extensions/review.ts, docs/configuration.md, docs/venom-config.schema.json]
features: [automation.review]
---

`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 {#example}

```bash
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 {#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 {#prs}

```bash
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](/docs/automation/review-action.md).

## A git hook {#hook}

```bash
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 {#more}

- `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 {#self-review}

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 {#settings}

```yaml
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](/docs/automation/review-action.md): a pull request review bot for GitHub Actions and GitLab CI.
- [Spec to pull requests](/docs/automation/spec-to-pr.md) reviews each slice before opening its PR.
