Skip to content
Guided Review
Documentation

How to review a GitHub pull request

Read the PR description, inspect the changed code, verify the behavior, then leave feedback and choose a review outcome. Start with GitHub’s own diff; the steps below also show how to continue in Guided Review’s Chrome extension overlay.

For a local branch, commit, or working tree, use the CLI instead. To use the overlay, install the Chrome extension.

Open a pull request

Open the repository’s Pull requests tab and select the PR. Read its description and linked issue before opening the diff. Identify the intended behavior, compatibility constraints, and the evidence the author supplied. If the expected outcome is unclear, ask before judging the implementation.

You can start Guided Review from Conversation, Files changed, or Commits.

If the button is missing, see Troubleshooting.

Inspect the diff in GitHub

You can review a PR without installing an extension:

  1. Open Files changed. Choose unified view for edits in sequence or split view to compare old and new code side by side.
  2. Use the file tree or filters to focus on related files. Keep track of what you filtered out so it gets a separate pass.
  3. Read the implementation with its callers and tests. Expand context or open the full file when a changed line depends on code outside the patch.
  4. Mark a file Viewed after inspecting it. That tracks reading progress; it does not establish that the change works.

GitHub’s reviewing proposed changes documentation covers its native diff controls. For a short, self-contained change, you may finish the reading there. The same GitHub documentation covers commenting and submitting a review. Use the overlay below when related changes are spread across files.

Before choosing an outcome, verify one concrete behavior. For example, if a retry change should stop after the configured limit, trace the loop condition and find a test that asserts the final attempt count. Run the relevant repository checks when possible; a green check on an unrelated path does not answer that question. The code review checklist gives a broader set of checks.

Start Guided Review

Click Start Guided Review on the PR page. The overlay opens and loads the diff.

With an AI provider configured, review units appear as your model organizes related changes. Without a key, you can read one unit per changed file, in diff order.

You can also start from the Guided Review toolbar icon while a PR tab is active. For pinning the icon or opening reviews automatically on Files changed, see Chrome Extension.

Connection failures after a key is set: Troubleshooting.

Follow the Walkthrough

Start with the change summary, then follow the review units. Each unit brings related changes together. See Reading the overlay for a map of the controls.

For each unit you can:

  • Read the unit’s title and guidance (take summaries with a grain of salt — see the FAQ)
  • See the linked hunks from the real diff (default unified view; switch with v u / v s, or the toolbar — choice is remembered). Images and binary files use a preview or empty state instead of a line patch.
  • Move next / previous with the footer or keyboard shortcuts

The model chooses the order and writes guidance. The code you read comes from the real diff. Check the guidance against the code; you decide whether the change is correct. How a review plan works explains how units are built and validated.

The third review unit in a sample PR, showing the retry implementation, its tests, and guidance about the Retry-After boundary.

Sample PR: review the code beside the unit’s commentary. Select the screenshot for full size.

Search the diff

Press ⌘/Ctrl + F to search file paths and code across the whole PR diff. Pick a result to jump to the unit that owns that match. Full behavior: Keyboard shortcuts → Diff search.

Leave comments and submit

As you walk:

  1. Press c to enter comment mode, select lines, and draft line comments. Drafts stay local until you submit (privacy).
  2. When you’re ready, press ⌘/Ctrl + Enter (or use Submit Review) to choose Comment / Approve / Request Changes and send the review.

Submit needs GitHub connected. Following the walkthrough and drafting do not. Full shortcut list: Keyboard shortcuts.

Resume later

You can switch between a PR’s Conversation and Files changed tabs and resume the same review. Your progress and drafts remain available until the browser session ends. For storage limits and clearing a session, see Troubleshooting.

If something fails mid-flight, see Troubleshooting.

Next. Reading the overlay · CLI · How a review plan works · Leave line comments