twgh 0.2.0

Read-only GitHub reviewer CLI: triage, re-review diffs, comment threads

twgh

Read-only GitHub reviewer CLI: triage what needs you, re-review only what changed since you last looked (force-push robust), and see which of your comments were addressed — across github.com and GitHub Enterprise.

twgh never writes to GitHub — no approvals, no comments, no merges. It is the read side of reviewing; for actions it hands you off to the browser.

Install

From PyPI (requires Python ≥ 3.12):

uv tool install twgh      # or: pipx install twgh

From source:

make install      # uv tool install -e . + bash completion

Prerequisites

• The GitHub CLI gh, authenticated for each host you review on: gh auth login --hostname <host>. twgh borrows gh for auth, host routing, and transport; it never handles your token.

Use-cases

1. Triage — which PRs need me right now?

twgh status

Cross-repo rollup of every open PR you are review-requested on, commented on, or have reviewed. Per PR: author, your review state against the current head (needs_review / needs_re_review / up_to_date), and open-thread count. ★ marks PRs that moved since your last status run — new head or new comments, tracked via a local snapshot (the first run deliberately flags nothing). --json for scripting.

2. Re-review — what changed since I last looked?

twgh diff <ref>

The author pushed again; you don't want to re-read the whole PR. diff anchors on your last submitted review (else your last inline comment) and shows anchor→HEAD, restricted to the files you commented on (--all for the whole PR). The anchor is a commit OID, so the diff survives force-pushes and rebases. With no prior review there is nothing to re-diff — it points you at twgh open instead.

3. Catch up — what was said while I was away?

twgh comments <ref>

A chronological reading view of everything said on a PR: top-level comments and inline review comments, sorted by time. Think of it as a chat log — you read top to bottom to understand the full conversation timeline. Comments in resolved threads are hidden (--all to include), --by <user> / --mine to filter.

Use comments when you want to understand what happened — context, history, the sequence of arguments.

4. Follow up — were my comments addressed?

twgh threads [<ref>]

An action-oriented triage view: one row per review conversation with a verdict showing whether it still needs attention:

• ✓ resolved — the thread is marked resolved
• ~ changed — the anchored code moved since the comment (inspect with twgh diff)
• · untouched — the point still stands as written

Use threads when you want to decide what to act on — scan, triage, move on.

Omit <ref> for a global inbox of open threads across all PRs that involve you. --mine / --by <user> to filter, --all to include resolved.

threads vs comments

Both draw from the same PR data but serve different workflows:

	threads	comments
Unit	one row per conversation	one row per comment
Order	by file path	by time
Key info	actionable verdict	full message body
Question answered	"what needs my response?"	"what was said?"
Scope	single PR or global inbox	single PR only

5. Act — everything twgh stays out of

twgh open <ref>

Opens the PR in the browser for the write actions: approving, replying, resolving, merging.

PR references

<ref> is a PR URL, host/owner/repo#N, owner/repo#N, owner/repo/N, or a bare number inside a repo checkout. status prints URLs — paste them straight back.

Host selection

-H/--gh-host overrides $GH_HOST, which defaults to github.com. Works as a global option (twgh -H bmw.ghe.com status) or per command.

Configuration

Optional TOML config at ~/.config/twgh/config.toml (override with --config). Bootstrap a starter with:

twgh edit --init

Author exclusion

Hide PRs from bots/service accounts in status and threads (inbox mode):

[exclude]
authors = ["dependabot[bot]", "self-hosted-renovate[bot]"]

# Per-host additions (extends the global list):
[exclude."github.enterprise.com"]
authors = ["renovate-enterprise[bot]"]

Override the exclusion list to show a specific author:

twgh status --author "dependabot[bot]"

Development

make test              # pytest + coverage (floor 85%)
make static-analysis   # ruff lint-fix, format, ty