gh-prs 0.7.0__tar.gz

gh_prs-0.7.0/.github/workflows/python-publish.yml

@@ -0,0 +1,68 @@
+# Publishes the package to PyPI when a GitHub release is published, then
+# triggers the Homebrew tap (denrou/homebrew-gh-prs) to regenerate its formula.
+# Same pipeline as denrou/ggit.
+
+name: Upload Python Package
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  release-build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Build release distributions
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/gh-prs/${{ github.event.release.name }}
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish release distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  update-homebrew:
+    runs-on: ubuntu-latest
+    needs:
+      - pypi-publish
+    steps:
+      - name: Trigger Homebrew tap update
+        env:
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: gh workflow run update-formula.yml --repo denrou/homebrew-gh-prs

gh_prs-0.7.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

gh_prs-0.7.0/.python-version

@@ -0,0 +1 @@
+3.14

gh_prs-0.7.0/CLAUDE.md

@@ -0,0 +1,172 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+uv run gh-prs               # Run the CLI (default: PRs needing attention)
+uv run gh-prs -c            # PRs you created
+uv run gh-prs -r            # PRs awaiting your review
+uv run pytest               # Run tests
+uv run ruff check .         # Lint
+uv run ruff format .        # Format
+uv add <pkg>                # Add dependency
+uv add --dev <pkg>          # Add dev dependency
+```
+
+## Architecture
+
+Four-module design inside `gh_prs/`:
+
+- **`gh.py`** — Stateless wrapper around the `gh` CLI, relying on the user's
+  existing `gh auth` session. Exposes a `PullRequest` dataclass plus
+  `fetch_prs()`, `count_prs()`, `fetch_pr_head()`, `ALL_QUALIFIERS`,
+  `DEFAULT_STALE_AFTER`, and the `GhError` exception.
+- **`snooze.py`** — Local per-PR snooze store (`{PR url: {oid, until}}` JSON
+  at `$XDG_CONFIG_HOME/gh-prs/snooze.json`). Pure I/O + partitioning helpers;
+  no `gh` calls. Raises `SnoozeError`.
+- **`config.py`** — Human-authored settings (`{stale_after}` JSON at
+  `$XDG_CONFIG_HOME/gh-prs/config.json`), kept separate from the
+  machine-managed snooze store so a hand-edit can't corrupt snooze state.
+  Reuses `snooze.parse_duration`; missing file → defaults; raises
+  `ConfigError`.
+- **`cli.py`** — Command-line interface (argparse + [rich](https://rich.readthedocs.io/)).
+  Fetches and prints grouped/colored tables. Entry point is `gh_prs.cli:main`.
+
+### Loading (single GraphQL round-trip per qualifier)
+
+`fetch_prs(qualifiers)` runs one `gh api graphql` search per qualifier
+(`author`, `review-requested`, `reviewed-by`, `assignee`, `involves`) in
+parallel threads.
+Each search fetches everything in one shot — review decision, mergeability,
+CI rollup state, `latestReviews`, `reviewRequests`, plus the viewer's login —
+so there is no per-PR enrichment phase. `attention_reasons` is computed by the
+pure `_attention_reasons()` helper (unit-tested in `tests/test_gh.py`).
+
+Performance notes (measured once; exact figures drift, the ratios hold):
+
+- GitHub executes aliased search blocks _sequentially_ within one GraphQL
+  request — that's why each qualifier gets its own parallel request (cost =
+  slowest search, not the sum).
+- GitHub also throttles concurrent searches per token; `-a` is bounded by
+  `involves:@me`, the slowest search by far.
+- Node _hydration_ dominates search cost, not the search itself — a
+  count-only `issueCount` query is roughly an order of magnitude faster than
+  a hydrated one. `count_prs()` exploits this for single-qualifier `--count`
+  (`-c`/`-r`), the status-bar polling path.
+- Each search is capped at `_SEARCH_LIMIT` (100) nodes; searches are
+  `sort:updated-desc`, so truncation keeps the most recently updated PRs, and
+  when `issueCount` exceeds the cap `fetch_prs()` reports the truncation
+  through its `on_warning` callback (the CLI prints it to stderr). Counts
+  from `count_prs()` are exact regardless of the cap.
+
+### Error handling
+
+"Error" must never look like "nothing to do" (critical for `--count` in status
+bars). All `gh` failures raise `GhError` — including per-qualifier search
+failures (partial results would silently hide PRs), subprocess timeouts
+(60 s), and any deviation from the expected GraphQL response envelope
+(validated in `_graphql()`/`_search()`). The same fail-safe direction applies
+to per-PR fields: unknown CI states map to `PENDING`, and "ready" requires a
+positive `MERGEABLE` (GitHub reports `UNKNOWN` while recomputing
+mergeability). The CLI prints errors to stderr and exits non-zero (130 on
+Ctrl-C).
+
+### Attention logic (`_attention_reasons`)
+
+A non-draft PR needs attention when any of these hold:
+
+- **review** — your review is requested (or your prior review was dismissed)
+  and you have no active approval / changes-requested. Hidden when: the PR is
+  conflicting (a review would be staled by the rebase); the overall decision
+  is `CHANGES_REQUESTED` (author is reworking it); or it's `APPROVED` —
+  mergeable without you — unless you are personally on the
+  requested-reviewers list (`review_requested_explicitly`, i.e. requested as
+  a User, not through a Team).
+- **new-commits** — you reviewed someone else's PR (`APPROVED`,
+  `CHANGES_REQUESTED`, `COMMENTED`, or `DISMISSED` — the latter for repos
+  that auto-dismiss stale reviews on push) and the head oid no longer
+  matches the oid your review was submitted against (`latestReviews.commit`
+  vs `headRefOid`) — new commits or a rebase the author forgot to re-request
+  review for. Commit identity is compared, not `committedDate`: committer
+  timestamps are mutable metadata. A missing oid on either side counts as
+  "moved" (unknown must never read as "nothing to do"); only both-missing
+  stays quiet. Hidden when: the PR is conflicting (more commits are coming);
+  the **review** reason already fired (no double listing); or you authored
+  the PR (a comment review on your own PR must not self-flag). Surfaced by
+  the `reviewed-by:@me` search in the default view — review requests
+  disappear once fulfilled, so these PRs match no other attention qualifier.
+  When the `latestReviews` 50-node cap hides your review on a `reviewed-by`
+  PR, `fetch_prs` reports the contradiction through `on_warning` instead of
+  silently skipping the PR.
+- **ready** — you authored it, it's `APPROVED`, CI is green (or none), and it's
+  not conflicting.
+- **ci-failed** — you authored it and a check is failing.
+- **conflict** — you authored it and it has merge conflicts (independent of
+  `ci-failed`; a PR can have both).
+- **stale** — a soft nudge: you authored it, it's still awaiting review (not
+  yet `APPROVED`, and not `CHANGES_REQUESTED` — the author isn't reworking
+  it), nothing else actionable fired (`not reasons`, so no `ready`/`ci-failed`
+  /`conflict`), and it has gone untouched (`updatedAt`) longer than the
+  staleness threshold — time to ping the reviewers. The threshold is
+  `DEFAULT_STALE_AFTER` (3 days), overridable via `config.json`'s
+  `stale_after` or the `--stale-after` flag. This reason is the one place
+  that **inverts** the house fail-safe: `_is_stale` treats a missing /
+  unparseable / naive `updatedAt` as _not_ stale, because a nudge is additive
+  and non-actionable — defaulting an unknown age to "stale" would fabricate a
+  reason on a possibly-fresh PR. Disabled entirely when `stale_after` is
+  `None` (config `null`) or `now`/`stale_after` aren't passed to
+  `_attention_reasons` (so a bare `_attention_reasons(pr)` never returns it).
+
+### Configuration (`config.py`, applied in `cli.py`)
+
+User settings live in `$XDG_CONFIG_HOME/gh-prs/config.json`, separate from the
+machine-managed `snooze.json` (opposite fail-safe needs; a hand-edit must not
+be able to corrupt snooze state). Today the only key is `stale_after` — a
+duration string (`"3d"`, `"1w"`) parsed by `snooze.parse_duration`, or `null`
+to disable the **stale** nudge. Only the view path reads it, and it degrades
+to defaults with an on-stderr warning on any error (the tool never writes it,
+so there is nothing to clobber). Resolution order for the threshold:
+`--stale-after` flag → `config.json` → `DEFAULT_STALE_AFTER`. A bad flag value
+is a hard error (explicit user input); a bad config file only warns.
+
+### Snoozing (`snooze.py`, applied in `cli.py`)
+
+`--snooze <pr>...` records each PR's head oid plus an expiry timestamp
+(default 24h, `--for 12h/3d/1w`); the default attention view (table and
+`--count`) then hides the PR while _both_ hold: head unchanged and window
+open. The same fail-safe direction as everywhere else applies: an unknown
+oid, an uncomparable timestamp, a moved head, an elapsed window, or an
+unreadable store all _show_ the PR (a corrupt store only warns on the view
+path, but is fatal for `--snooze`/`--unsnooze`, which must not clobber the
+file). Dead entries are pruned — with an on-stderr "snooze expired" warning
+when the PR actually resurfaced — and the view reports how many
+attention-worthy PRs it withheld. Explicit views (`-c`/`-r`/`-a`), fast
+counts, and `--json` never consult the store — their output stays exact.
+Entries whose PR no longer appears in any search are kept while their window
+is open (the PR may be closed _or_ merely beyond the 100-node cap; deleting
+on absence would lose live snoozes) and pruned quietly once it elapses.
+
+`--snooze`/`--unsnooze` each take one or more PR references, following `gh`'s
+own conventions: a bare number (`123`) or a full URL. A bare number is scoped
+by `-R/--repo owner/repo`, or — when that's omitted — the repository of the
+current directory. Bare numbers are resolved through `gh.resolve_pr()` (a
+`gh pr view` call), so their canonical URL and host come straight from `gh`
+and enterprise instances work without host-specific URL construction; a full
+URL is canonicalized offline by `normalize_pr_url()` (keeping `snooze.py`
+free of `gh` calls), so `--unsnooze <url>` needs no network. The old
+`owner/repo/123` / `owner/repo#123` shorthand was removed in favor of a
+number plus `--repo`; both forms now hard-error. References resolve
+independently: a bad or not-snoozed one is reported to stderr and skipped
+while the rest are applied, the store is written once, and a partial batch
+exits non-zero — never clobbering the file.
+
+## Notes
+
+- `ruff` rule `E501` (line length) is not enforced.
+- GraphQL `statusCheckRollup.state` is normalized via `_ROLLUP_STATE`; unknown
+  future states map to `PENDING` so "unrecognized" never counts as passing.
+- PR titles are attacker-controlled: they are stripped of control characters
+  at ingestion (`from_graphql`) and markup-escaped at render (`_title_cell`).
+  Keep both when touching those paths.

gh_prs-0.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Denis Roussel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gh_prs-0.7.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: gh-prs
+Version: 0.7.0
+Summary: CLI for listing GitHub pull requests that need your attention, powered by gh CLI
+Author-email: Denis Roussel <deroussel@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: rich>=14.0.0
+Description-Content-Type: text/markdown
+
+# gh-prs
+
+A simple CLI that lists the GitHub pull requests you need to act on, powered by
+the `gh` CLI. No TUI — just readable, colored, grouped output.
+
+By default it shows only the PRs that need your attention:
+
+- **Needs your review** — PRs where your review is requested and still needed:
+  once the PR is approved (mergeable without you) it is hidden unless you are
+  personally on the requested-reviewers list (not just through a team), and it
+  is also hidden while changes are requested (the author is reworking it).
+  Drafts are excluded (not ready for review), as are conflicting PRs (a review
+  would be staled by the rebase). A PR also resurfaces here when your previous
+  review was dismissed.
+- **New commits since your review** — PRs you already reviewed (approved,
+  requested changes, left a review comment, or had your review dismissed by a
+  push) whose head commit is no longer the one you reviewed — new commits or
+  a rebase the author forgot to re-request review for; the case that is
+  otherwise easy to miss. Hidden while the PR is conflicting (more commits
+  are coming anyway). A PR never appears both here and in **Needs your
+  review**: whenever it qualifies there (e.g. a re-request after a
+  comment-only review), that section wins; a re-request after your
+  still-standing approval keeps it here.
+- **Ready to ship** — PRs you created that are approved, with CI green (or no
+  checks) and no conflicts.
+- **CI failed** — PRs you created where a check is failing.
+- **Conflicts to resolve** — PRs you created that have merge conflicts.
+- **Waiting on review — time to nudge** — PRs you created that are still
+  awaiting review and have gone quiet longer than the staleness threshold
+  (3 days by default). There's nothing for _you_ to do — the code is fine, CI
+  is green, no conflicts — but it has been sitting long enough that pinging the
+  reviewers is warranted. Any new activity (a comment, a commit) resets the
+  clock, so it won't nag while there's discussion. Change the threshold with
+  `--stale-after 5d` or the `stale_after` config setting; set it to `null` in
+  the config to turn the nudge off entirely.
+
+## Prerequisites
+
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated (`gh auth login`)
+- Python 3.14+
+- [uv](https://docs.astral.sh/uv/)
+
+## Install
+
+With [Homebrew](https://brew.sh/):
+
+```bash
+brew install denrou/gh-prs/gh-prs
+```
+
+Or from [PyPI](https://pypi.org/project/gh-prs/):
+
+```bash
+uv tool install gh-prs
+```
+
+Or straight from the repository:
+
+```bash
+uv tool install gh-prs --from git+https://github.com/denrou/gh-prs.git
+```
+
+### As a `gh` alias
+
+```bash
+gh alias set --shell prs 'gh-prs'
+```
+
+Then simply run:
+
+```bash
+gh prs
+```
+
+## Usage
+
+```bash
+gh prs              # PRs that need your attention (default)
+gh prs -c/--created # every open PR you created
+gh prs -r/--review  # every PR awaiting your review
+gh prs -a/--all     # every PR you are involved with
+gh prs --json       # raw JSON (for scripting)
+gh prs --count      # print only the PR count for the selected view
+                    # (attention count by default; handy for status bars)
+gh prs --no-color   # disable colored output
+
+gh prs --snooze 123           # hide a PR (of the current repo) for 24h
+gh prs --snooze 123 -R o/r    # …of another repo (owner/repo)
+gh prs --snooze 12 34 --for 3d  # …several at once, for a custom window (12h, 3d, 1w)
+gh prs --unsnooze 123         # remove a PR's snooze
+gh prs --snoozed              # list snoozed PRs
+
+gh prs --stale-after 5d  # flag your review-waiting PRs quiet this long
+```
+
+`--count` exits non-zero when fetching fails, so status-bar scripts can tell
+"no PRs" apart from "the lookup broke". With `-c` or `-r` it uses a fast
+count-only query (well under a second) — ideal for frequent polling.
+
+### Snoozing
+
+Sometimes a PR legitimately needs _someone's_ attention but not yours — say a
+dependency bump routed to you through a team when a teammate is the natural
+reviewer. `gh prs --snooze <pr>...` hides one or more PRs from the default
+attention view. Reference a PR the way `gh` does: a bare number, scoped by
+`-R/--repo owner/repo` (or the repository of the current directory when
+omitted), or a full URL. Bare numbers are resolved through `gh`, so Enterprise
+hosts work too.
+
+A snooze lasts 24 hours by default (`--for 12h`/`3d`/`1w` to change) and is
+also tied to the PR's head commit at snooze time: whichever comes first — the
+window elapsing or new commits landing — resurfaces the PR with a warning and
+drops the snooze, so you acknowledge a specific state for a bounded time,
+never future work. The attention view prints how many snoozed PRs it withheld
+on stderr — hiding is visible, never silent. Explicit views (`-c`/`-r`/`-a`),
+`--count` for those views, and `--json` ignore snoozes entirely, so scripts
+and exact counts are unaffected.
+
+Snoozes are stored locally in `~/.config/gh-prs/snooze.json` (honors
+`$XDG_CONFIG_HOME`); they never touch the PR on GitHub.
+
+### Configuration
+
+Settings live in `~/.config/gh-prs/config.json` (honors `$XDG_CONFIG_HOME`),
+separate from the snooze store. It's optional — every setting has a default.
+Today the only key is `stale_after`, the silence threshold for the
+**Waiting on review** nudge:
+
+```json
+{ "stale_after": "5d" }
+```
+
+Accepts the same duration syntax as `--for`/`--stale-after` (`12h`, `3d`,
+`1w`), or `null` to disable the nudge. The `--stale-after` flag overrides the
+file for a single run. An unreadable or invalid config only warns and falls
+back to the 3-day default, so a typo never breaks the tool.
+
+For status bars, prefer the `uv tool install` binary (`~/.local/bin/gh-prs`)
+over `uv run` inside the repo — it skips ~250 ms of project resolution per
+invocation.

gh_prs-0.7.0/README.md

@@ -0,0 +1,140 @@
+# gh-prs
+
+A simple CLI that lists the GitHub pull requests you need to act on, powered by
+the `gh` CLI. No TUI — just readable, colored, grouped output.
+
+By default it shows only the PRs that need your attention:
+
+- **Needs your review** — PRs where your review is requested and still needed:
+  once the PR is approved (mergeable without you) it is hidden unless you are
+  personally on the requested-reviewers list (not just through a team), and it
+  is also hidden while changes are requested (the author is reworking it).
+  Drafts are excluded (not ready for review), as are conflicting PRs (a review
+  would be staled by the rebase). A PR also resurfaces here when your previous
+  review was dismissed.
+- **New commits since your review** — PRs you already reviewed (approved,
+  requested changes, left a review comment, or had your review dismissed by a
+  push) whose head commit is no longer the one you reviewed — new commits or
+  a rebase the author forgot to re-request review for; the case that is
+  otherwise easy to miss. Hidden while the PR is conflicting (more commits
+  are coming anyway). A PR never appears both here and in **Needs your
+  review**: whenever it qualifies there (e.g. a re-request after a
+  comment-only review), that section wins; a re-request after your
+  still-standing approval keeps it here.
+- **Ready to ship** — PRs you created that are approved, with CI green (or no
+  checks) and no conflicts.
+- **CI failed** — PRs you created where a check is failing.
+- **Conflicts to resolve** — PRs you created that have merge conflicts.
+- **Waiting on review — time to nudge** — PRs you created that are still
+  awaiting review and have gone quiet longer than the staleness threshold
+  (3 days by default). There's nothing for _you_ to do — the code is fine, CI
+  is green, no conflicts — but it has been sitting long enough that pinging the
+  reviewers is warranted. Any new activity (a comment, a commit) resets the
+  clock, so it won't nag while there's discussion. Change the threshold with
+  `--stale-after 5d` or the `stale_after` config setting; set it to `null` in
+  the config to turn the nudge off entirely.
+
+## Prerequisites
+
+- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated (`gh auth login`)
+- Python 3.14+
+- [uv](https://docs.astral.sh/uv/)
+
+## Install
+
+With [Homebrew](https://brew.sh/):
+
+```bash
+brew install denrou/gh-prs/gh-prs
+```
+
+Or from [PyPI](https://pypi.org/project/gh-prs/):
+
+```bash
+uv tool install gh-prs
+```
+
+Or straight from the repository:
+
+```bash
+uv tool install gh-prs --from git+https://github.com/denrou/gh-prs.git
+```
+
+### As a `gh` alias
+
+```bash
+gh alias set --shell prs 'gh-prs'
+```
+
+Then simply run:
+
+```bash
+gh prs
+```
+
+## Usage
+
+```bash
+gh prs              # PRs that need your attention (default)
+gh prs -c/--created # every open PR you created
+gh prs -r/--review  # every PR awaiting your review
+gh prs -a/--all     # every PR you are involved with
+gh prs --json       # raw JSON (for scripting)
+gh prs --count      # print only the PR count for the selected view
+                    # (attention count by default; handy for status bars)
+gh prs --no-color   # disable colored output
+
+gh prs --snooze 123           # hide a PR (of the current repo) for 24h
+gh prs --snooze 123 -R o/r    # …of another repo (owner/repo)
+gh prs --snooze 12 34 --for 3d  # …several at once, for a custom window (12h, 3d, 1w)
+gh prs --unsnooze 123         # remove a PR's snooze
+gh prs --snoozed              # list snoozed PRs
+
+gh prs --stale-after 5d  # flag your review-waiting PRs quiet this long
+```
+
+`--count` exits non-zero when fetching fails, so status-bar scripts can tell
+"no PRs" apart from "the lookup broke". With `-c` or `-r` it uses a fast
+count-only query (well under a second) — ideal for frequent polling.
+
+### Snoozing
+
+Sometimes a PR legitimately needs _someone's_ attention but not yours — say a
+dependency bump routed to you through a team when a teammate is the natural
+reviewer. `gh prs --snooze <pr>...` hides one or more PRs from the default
+attention view. Reference a PR the way `gh` does: a bare number, scoped by
+`-R/--repo owner/repo` (or the repository of the current directory when
+omitted), or a full URL. Bare numbers are resolved through `gh`, so Enterprise
+hosts work too.
+
+A snooze lasts 24 hours by default (`--for 12h`/`3d`/`1w` to change) and is
+also tied to the PR's head commit at snooze time: whichever comes first — the
+window elapsing or new commits landing — resurfaces the PR with a warning and
+drops the snooze, so you acknowledge a specific state for a bounded time,
+never future work. The attention view prints how many snoozed PRs it withheld
+on stderr — hiding is visible, never silent. Explicit views (`-c`/`-r`/`-a`),
+`--count` for those views, and `--json` ignore snoozes entirely, so scripts
+and exact counts are unaffected.
+
+Snoozes are stored locally in `~/.config/gh-prs/snooze.json` (honors
+`$XDG_CONFIG_HOME`); they never touch the PR on GitHub.
+
+### Configuration
+
+Settings live in `~/.config/gh-prs/config.json` (honors `$XDG_CONFIG_HOME`),
+separate from the snooze store. It's optional — every setting has a default.
+Today the only key is `stale_after`, the silence threshold for the
+**Waiting on review** nudge:
+
+```json
+{ "stale_after": "5d" }
+```
+
+Accepts the same duration syntax as `--for`/`--stale-after` (`12h`, `3d`,
+`1w`), or `null` to disable the nudge. The `--stale-after` flag overrides the
+file for a single run. An unreadable or invalid config only warns and falls
+back to the 3-day default, so a typo never breaks the tool.
+
+For status bars, prefer the `uv tool install` binary (`~/.local/bin/gh-prs`)
+over `uv run` inside the repo — it skips ~250 ms of project resolution per
+invocation.