Perch
Guide contents

Field guideReview a change

Review a worktree with agents

Choose which agents should read the diff. Check their findings and edit the draft comments before you send a review to GitHub.

Choose your reviewers

Open Review → Settings. Check the agents you want, choose a model and effort for each, then click Run review. An unavailable agent shows the reason.

Review menu with Claude and Codex selected, model and effort controls, a Changes selector, and Run review

On a PR, click Open beside Your review to check drafts, edit the summary, and choose a verdict. The toolbar shows run progress and counts drafts. Worktrees without a PR show only agent settings.

Choose what to review

All selected agents review the same diff, from the last commit shared with the base branch to the endpoint you choose in Changes. This works on Perch-created and registered worktrees, with or without a PR.

  • Last commit ends at HEAD and excludes uncommitted files.
  • Working tree includes staged, unstaged, and untracked files. Perch takes a snapshot and leaves the branch, files, and Git index untouched.

Perch defaults to Working tree if Files shows uncommitted changes, or your branch has edits but no new commits. Otherwise it selects Last commit. Perch skips empty diffs. Staged-only, single-commit, and incremental reviews are unavailable.

Look in Conversation for all findings. They also appear in Uncommitted and Branch while you’re on the reviewed commit. For new lines the file must still match the snapshot. For old lines the merge base must match.

Use the instructions box to focus the review, for example “Review rfcs/multi_get.md only.” This keeps the same diff. Claude gets the instructions with /code-review. Codex gets them separately because --base cannot take a custom prompt. Retry reuses the instructions saved in history.

On a PR, reviewers also read the discussion in ~/.perch/context/review-<id>/. They’re asked to skip issues already raised in unresolved threads and identify whose requested changes are still missing.

Reopen or repeat a review

Perch saves a read-only copy of the diff, commits, and files used for each review. You can reopen the exact lines a reviewer saw after the branch moves or an external worktree is deleted. Opening an old review leaves your current checkout alone.

Claude Code (2.1.223+) and Codex (0.155.1+) use their own review commands, /code-review and codex exec review. Claude’s hosted ultra review mode is unavailable in Perch. Gemini (Antigravity CLI 1.5.5+) and OpenCode (2.3.0+) use Perch’s review instructions. OpenCode reads the saved diff with file tools and no shell. The menu explains why a missing or incompatible CLI cannot run.

Retry runs the same review against the saved snapshot with the same settings. Review latest takes a new snapshot of the branch. When a reviewer finds the same problem again, Perch keeps the discussion in one thread. History includes each attempt, including failures and reviews that found nothing.

Check drafts before posting

On an open PR, findings on lines GitHub accepts become draft comments. Read, edit, or delete them before submitting your review. The card shows the reviewer and severity. Deleting a draft dismisses the finding. Dismissing a finding or marking it as a duplicate removes its draft.

A draft needs a line in the PR diff (a changed line or one of its three context lines), the same head commit, and the same merge base as GitHub. Other findings stay in Perch, including every finding on a worktree without an open PR. See Posting for how drafts reach GitHub.

You decide when to run a review and which findings to post. An agent review leaves your files and GitHub threads as they are. Follow-up questions stay in Perch until you post them.