riff

    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:name and label:name narrow by field. The repo chips under the header set repo: for you.
    • Open by URL: paste a PR URL or owner/repo#123 into 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.