The app
Pull requests
The PR list that ranks what needs you, and the PR page with its checks, reviews, threads and merge.
The PR list shows every pull request you wrote or were asked to review, ranked by what you should do next. Open one to see its checks, reviews and threads on a single page, and to merge it.
Riff needs a GitHub token first. See GitHub.
Open PRs and tabs
The sidebar keeps the PRs you open as tabs, under Open. ⌘ 1–9 picks one, Ctrl Tab steps through them, and Close all closes them (drafts stay saved). Hover a row for a card with its status. Riff keeps the five most recent tabs loaded, with their scroll position and open file; older ones reload when you pick them, and tabs left alone for 30 minutes unload. Below Open, Recent lists PRs you opened before.
The sidebar also holds Working tree (see Diffs), the agent and Settings.
The PR list
Each row is a PR, or a stack of them. Every row says why it is there (the reason), who or what it waits on, and often offers one action.
Sections
Rows fall into sections, most urgent first. The first four make up Needs you.
| Section | What is in it |
|---|---|
| Continue reviewing | Reviews you started in riff: some files viewed, or drafts waiting |
| Requested from you | Review requested from you, or pushed since you reviewed |
| Ready to merge | Your PRs that are approved, green and mergeable |
| Fix | Your PRs with a conflict, failing CI, requested changes or unresolved threads |
| Via your teams | Review requested from a team you are in |
| Yours, waiting for review | Your PRs with nothing for you to do yet |
| Not waiting on you | Drafts, and PRs you already reviewed |
| Stale | No update in 14 days |
| Snoozed | Hidden until something changes |
Needs-you sections never turn stale. A stack sits in the section of its most urgent PR. Fix rows are ordered by how close they are to done: failing CI first, then requested changes, open threads and conflicts, with approved PRs ahead of the rest. Fix shows the first five; Show all lists the rest. On wide windows a nav beside the list jumps to each section.
Reasons and actions
The reason is a short phrase such as “Requested from you”, “Pushed since your review”, “Failing: build +1”, “Changes requested by sam”, “2 unresolved · 1 waiting on you”, “CI running · 3/8”, “Ready to merge” or “Waiting on sam”. For your own PRs the order of checks is: conflict, CI, requested changes, threads, draft, CI running, approval.
A row offers at most one action. Press a on the focused row to use it.
| Reason | Action |
|---|---|
| Continue reviewing | Resume: opens the first file you have not viewed |
| Ready to merge | Merge, with the methods the repository allows |
| Merge conflict | Resolve: opens the conflicts on GitHub |
| CI failing | Check: opens the failing check on GitHub |
| Changes requested | Re-request review from the people who asked |
| Waiting for review | Copies a nudge message for the requested reviewers |
Review rows also say what moved since you last opened the PR in riff: “Not opened yet”,
“New commits since you looked” or “Updated since you looked”. Your progress shows on the row:
files viewed (5/11), your drafts, and the state of an AI review.
A row also has the PR’s size, its Jira ticket with status and assignee when Jira is set up, and five status icons (review, CI, threads, branch, dependencies). Hover one for the full text.
The row’s Prepare review button starts an AI review without opening the PR; while it runs, the button stops it.
Filters, views and groups
- View: All, Theirs (PRs you review) or Mine.
- Group by: Sections (the default), Epic or Team. The last two come from Jira; see Stacks and dependencies.
- Filter box: type to match title, number, repo, author or branch.
repo:name,author:nameandlabel:namenarrow by field. The repo chips under the header setrepo:for you. - Open by URL: paste a PR URL or
owner/repo#123into the filter box and press Enter to open that PR, even if it is not in your list.
While CI and mergeability load, your own PRs show as “checking” placeholders.
A stack is folded to its most urgent layers in the Needs-you sections and closed elsewhere.
x opens it to every layer.
Snooze
Snooze hides a PR until its head commit or review decision changes. Use the bell on a row,
or press s. Snoozed PRs sit under Snoozed and come back on their own. Snoozes are
stored in riff only, and riff pr snooze shares them.
Refresh and updates
The list refreshes when you focus the window and every 15 minutes while it is visible.
Refresh (or r) asks GitHub right now. If GitHub cannot be reached you see
“Offline copy from …” and the saved list.
Changes that would reorder rows are held while your pointer or focus is on the list. An updates pill appears; click it to apply them.
| Key | Does |
|---|---|
j / k |
Move between rows |
Enter |
Open the row |
a |
Run the row’s action |
x |
Expand or fold a stack |
s |
Snooze or bring back |
/ |
Focus the filter |
r |
Refresh |
The PR page
A PR opens on three tabs: Summary, Files and Review. The header shows the title, state, who it waits on, a Refresh button, a link to GitHub, the ⋯ menu and the Review button. Under the tabs are the draft sync button, labels, the Jira ticket, the author, and the base and head branches (click the head branch to copy it). See Reviewing for Files and Review.
The Summary tab holds the merge status, the description, the activity feed and, in a column on the right at wide widths, the details.
Details
The details column shows the PR’s assignees and labels and, with Jira set up, a card for its ticket: key, status, type, assignee and epic, the ticket’s links (blocked by, blocks, same stack, relates to) and its acceptance criteria, description and testing instructions. See Jira tickets. Below 1280 px the ticket is one line above the status, with a Details button.
Activity
Activity lists reviews, threads, comments, pushes and review requests, newest first. The filter picks Relevant (people’s reviews and comments), All, Unresolved or Mine. Bot comments fold into one line. Comment posts a general comment on the PR immediately, unlike a line comment, which is a draft.
Merge status
The Summary tab opens with one verdict (“Ready to merge”, “Waiting on review”, “Blocked: 2 failing checks”, “Draft · not ready for review”, and so on) over four gates. Gates with nothing to act on fold into the verdict line; All gates shows them.
| Gate | Shows |
|---|---|
| Reviews | Approvals, requested changes and who is still asked |
| Checks | Failing, running and passed counts, with the log of each failure |
| Threads | Unresolved threads and who each waits on |
| Branch | Conflicts with, or behind, the base branch |
PRs with Jira links add Depends, Order and Unblocks gates. See Stacks and dependencies.
Reviews and re-requests
When someone requested changes and you pushed since, the Reviews gate offers Re-request review and a link to your changes since. Once asked, it shows Re-requested.
Checks and rerun
A failing check shows its failure and a Re-run button that reruns that run’s failed
jobs. From the terminal, riff pr rerun reruns every failing run.
Merge
The Merge button sits in the verdict header. Pick a method (squash, merge or rebase, as the repository allows) and optionally Delete branch after merge. It is disabled while the branch conflicts (“Resolve the conflicts first”): the Branch gate’s Resolve on GitHub opens GitHub’s conflict page, and so does the list row’s Resolve. A draft shows Ready for review instead.
The ⋯ menu converts a PR to draft, closes it, or reopens it.
Jira merge guard
If the PR’s Jira ticket is blocked by tickets that have not shipped, merging stops with
“Merge … before what it depends on?”. The dialog lists each blocker. Cancel keeps the
PR as is; Merge anyway goes ahead. riff pr merge stops the same way, with exit code 6,
and --ignore-deps overrides it. See riff pr.
Drafts and your pending review
Comments you save in riff are drafts. With Sync saved comments to your pending GitHub review on (Settings → Reviews, the default), each draft is also added to your pending review on GitHub, so it survives on another machine. Nothing is submitted until you submit.
The sync button in the tab bar shows the state of your drafts. Its popover lists every draft with its status, says whether GitHub holds a pending review, and has Sync now. Click a draft to jump to its line. With automatic push off, drafts on GitHub still come in and yours go up when you submit.
From the terminal
Everything on the list and the page is also in riff pr: inbox, status, checks,
threads, merge, rerun, rerequest, snooze. See riff pr.