When the inbox refreshes
Open Inbox for your GitHub notifications in GitHub’s order. Perch shows cached threads immediately, including ones you’ve read, and remembers Done and Snooze even if it can’t update the cache.

Click Refresh to bring new notifications into the list. Read indicators update in place. If the open discussion changes, Perch offers to reload it. CI results update automatically for the commit you’re viewing.
Perch polls at GitHub’s requested interval (X-Poll-Interval). It fetches all pages at startup and on the first poll after 15 minutes. Between full checks, it tests the first page’s ETag. Changes to older threads on github.com can take until the next full check to appear. A new login takes effect on the next poll.
Read state, Done, and snoozing
- Read. Opening an issue or PR from any sidebar tab marks it read on GitHub. Perch highlights the latest activity covered by an unread notification, opening a resolved thread if needed. Scroll to keep your place. Read threads reopen where you left them.
- Mark Unread sets a local reminder until you open the item. GitHub’s API cannot mark a thread unread. Perch remembers which update you read until new unread activity arrives.
- Done clears the notification in Perch and on GitHub. New unread activity brings it back. Your own comments and updates you’ve read leave it under Done. Perch checks for newer activity before clearing, but a comment arriving between that check and GitHub accepting Done can still be cleared.
- Unsubscribe also tells GitHub to ignore future activity on that thread.
- Snooze hides a thread in Perch until the time you choose or new unread activity arrives. Later today means 6 PM. The other presets use 8 AM. If no update arrives, the thread returns with its previous read state.
Move to Inbox restores a thread from View › Snoozed or View › Done. Done lists cleared threads GitHub still returns. Restoring one affects Perch only, until it qualifies for Done again.
When you merge or close a PR or close an issue, Perch treats the next minute’s activity as part of the close and marks the thread Done. Later unread comments bring it back. When someone else closes the item, its notification stays put.
To clear finished items together, choose State › Merged or Closed, then Mark N Done. Perch skips threads with newer unread activity and reports failures together. Unknown states, releases, and CI runs count as open. In Done and Snoozed, the bulk action is Move N to Inbox.
Issues and PRs open in Perch. Other notification types open on GitHub.
The sidebar's filter menus
Use the filter beside the search box to choose a view, repository, state, or sort order.
- Inbox shows active, snoozed, or done notifications. Filter by unread status or reason (review requested, yours, assigned, or mentioned). Yours includes items you opened. Sort newest or oldest first.
- Worktrees lists your worktrees. Recent lists everything you’ve opened. Each view remembers its sort order (last activity, last opened, or created). Both have an unread filter.
- Browse searches GitHub for items you own, need to review, were assigned, or were mentioned in. All searches the selected repository or all configured GitHub repositories. Sort by last activity or creation date.
The repository filter applies across tabs and includes repositories known from Inbox or Worktrees. State defaults to Any in Inbox and Worktrees and Open in Browse. Choose Merged or Closed for finished items.
Clearing a notification keeps its worktree and conversation. GitHub’s API can return Done history without identifying which threads are in its web inbox, so the two Done views can differ.
Finished runs on your own work
When an agent finishes an Ask, Work, or review run on a worktree without a pull request, Perch adds a local notification. The row names the repository, branch, and result, such as Claude · Work · 3 files or Review · 2 findings. Failures use the error color. Perch skips runs you were watching in the foreground, canceled runs, runs interrupted when you quit, and sessions started outside Perch.
Each worktree gets one inbox row for its most recent result. Open the item to mark it read, choose Mark Unread for a reminder, or choose Done to hide it until another run finishes. Look under View › Inbox with Yours or All selected. Local rows appear in time order alongside GitHub notifications and have no Snooze option.
Once the worktree has a pull request, its local row disappears. GitHub supplies its inbox notifications from then on. Perch still shows a notice when a run finishes.
Perch fetches a pull request or issue when you open a notification or open the item by repository and number. For agents, you can also enable GitHub history sync per repository.