gh-prlist

Configurable GitHub pull-request monitoring with clickable macOS notifications. The PyPI package is gh-prlist (prlist and pr-list are taken or blocked as too similar). The installed commands are gh-prlist, pr-list, and prlist. It requires the GitHub CLI (gh) to be installed and authenticated.

uvx gh-prlist setup
uvx gh-prlist list
uvx gh-prlist monitor
uvx gh-prlist monitor --own
uvx gh-prlist monitor --team
uvx gh-prlist monitor --own --team

setup writes TOML configuration to ~/.prlist. Command-line options override that file; run prlist <command> --help for all overrides.

The default policies show your open non-draft PRs with failing CI and non-draft team-review requests with green CI and no explicit merge conflict. monitor checks every ten minutes and writes a clickable report to ~/.cache/prlist/prs.html.

Each source can independently filter CI (green, failing, any) and mergeability (not_conflicting, conflicting, any). Notifications can include own PRs, team PRs, or both. Change-only notification state persists across monitor restarts.

Failure ignores are configurable per source as case-insensitive check-name substrings. They can be entered during setup or supplied repeatedly:

gh-prlist monitor --own --own-ignore-failure "Post Plan Checks"

Failed Post Plan Checks jobs are expanded into their failed workflow steps. This allows a team approval gate to count as green without hiding unrelated failures from the same parent job:

[team]
ignore_failures = ["Require Approval (Engineering Enablement)"]

For example, an Engineering Enablement approval gate is ignored, while Verify How It Was Tested Filled Out or Require Approval (SRE) remains red. Avoid ignoring the broad Post Plan Checks parent name when using this mode.

Each source can also require labels, which is how you narrow a team-review queue to one team's routing label. label_match = "any" (the default) keeps a PR carrying at least one of the labels; "all" requires every one of them:

gh-prlist monitor --team --team-label "teams/engineering-enablement"
gh-prlist monitor --team --team-label "teams/ee" --team-label "release" --team-label-match all

Labels are matched case-insensitively after the search, so PRs dropped by the filter still appear in the report's "filtered out" section, marked label filter. CI is only fetched for label matches, so narrowing by label makes a monitor cycle cheaper rather than more expensive.

Report rows open in a new tab and carry an eye toggle that tracks what you have already looked at. Opening a PR marks it seen (solid eye, dimmed row); clicking the eye toggles it back. The state lives in the browser's local storage and is keyed by the PR's last-updated time, so a PR you have already seen returns to unseen as soon as it gets a new push.

For clickable notification actions on macOS, install terminal-notifier. Without it, notifications fall back to osascript.