​

How a review fires

A Qodex review starts when a connected GitHub repo sends an event for a pull request. The most common triggers are opening a PR, pushing new commits, reopening a PR, marking a draft ready for review, changing the PR’s base branch, or asking manually with @qodex-ai review or the Run review button on the PR review page in Qodex.

​

Review sequence

1. Someone opens or pushes to a PR. GitHub posts the event to Qodex. If the repo is not connected to any Qodex project, the event is acknowledged and dropped.
2. Qodex posts a Check Run as in progress. A Qodex review check appears in the PR’s checks panel so the author knows a review is running.
3. The agent reviews the diff. Qodex pulls the unified diff, reads .qodex.yaml from the PR head, loads project memory, and runs a high-precision review pass. Findings below the 0.7 confidence floor are dropped.
4. Qodex posts comments. Findings on changed lines become inline comments. Findings outside the diff move into the walkthrough body under “Findings outside the diff.” The walkthrough also includes a summary, severity counts, and a “What Qodex checked” transparency block.
5. The Check Run completes. In advisory mode, the conclusion is neutral. In gated mode, the conclusion is failure only when a verified finding meets block_on_severity; otherwise it is success. Unverified findings never block.

The whole flow runs in the background. The webhook returns immediately so GitHub does not retry.

​

Re-running a review

Comment @qodex-ai review on the PR thread, or click Run review on the PR’s review record in Qodex (Code > PR review), to review the current head commit again. The Check Run on that same head SHA updates in place, so manual re-runs do not stack duplicate checks. When a person asks for a review, the walkthrough starts with “Triggered manually by” and their name. A manual review counts against the plan’s reviews-per-pull-request limit like any other review. If the PR has none left, Qodex replies with “Review limit reached” instead of starting a review. After a review finishes, the Run review button waits two minutes before it runs another one. After a successful review, Qodex normally focuses an automatic re-review on the files and lines changed since that earlier review. It falls back to the full PR when it cannot prove the earlier commit is an ancestor, the new change is too large, or the host cannot provide a complete readable delta. Existing findings carry forward rather than being repeated. Use @qodex-ai full review when you want Qodex to review the PR from scratch and disregard the earlier findings. See Slash commands for the full command list.

​

When Qodex skips a PR

Qodex skips a PR with a neutral Check Run when:

• The PR is a draft. Marking it ready for review starts a review.
• Automatic reviews are off for the repository (Automatic reviews in the repo’s review settings, or pr_review.enabled: false in .qodex.yaml). The Check Run is titled “Review on request”. Ask with @qodex-ai review or Run review, or turn automatic reviews back on.
• The project has used the pull requests its plan includes this month, or this PR has used every review its plan includes. The Check Run is titled “Qodex review skipped: plan limit”.
• The PR author is a bot.
• The changed files all match paths.exclude in .qodex.yaml.
• The author or base branch is outside the repo’s configured authors or base_branches allowlist.
• Automatic reviews were paused for the PR, or the PR description declares @qodex-ai ignore.
• The PR action is not one that starts a review. A labeled event, for example, is acknowledged but does not run a review.

See Troubleshooting for what to do in each case.

​

Related