watchgh

A GitHub activity timeline for your terminal. It shows the pull requests, reviews, and CI runs that need you, in the order they arrive.

Run wgh to open the timeline. It also starts a background poller that keeps GitHub in sync and sends desktop notifications when something needs you, even when no window is open. It signs in with your existing GitHub credentials (GITHUB_TOKEN if set, otherwise gh auth token).

Status: a personal pet project, maintained solo and as time allows. Shared in case it's useful. Issues and pull requests are welcome; I review them when I can, so replies may be slow, and small, focused changes get merged fastest. See CONTRIBUTING.md. Fork it freely under MIT.

Install

macOS only. The installer downloads the prebuilt wgh binary from the latest GitHub release and puts it on your PATH. No Go toolchain needed.

curl -fsSL https://raw.githubusercontent.com/asccigcc/watchgh/main/install.sh | bash

It installs to /usr/local/bin/wgh. Set BINDIR to change that, or WGH_TAG to pin a specific release:

BINDIR=/opt/homebrew/bin WGH_TAG=v0.7.0 bash install.sh

Then run it:

wgh

That opens the timeline and, on this first run, installs the background poller. Make sure the GitHub CLI is signed in first (gh auth login), since wgh uses its token.

Update

The updater upgrades your install in place to the latest release and restarts the background poller for you, so the running copy picks up the new binary right away:

curl -fsSL https://raw.githubusercontent.com/asccigcc/watchgh/main/update.sh | bash

It's a no-op when you're already current. Pin a tag or force a reinstall with WGH_TAG=v0.7.0 or WGH_FORCE=1. Check what you're running with wgh version.

Why the poller restart matters: it runs continuously, so replacing the file on disk doesn't change the copy already in memory — the updater's launchctl kickstart re-execs it onto the new binary. (Doing it by hand is wgh stop && wgh.)

Commands

wgh          # interactive timeline (prints plain text when piped)
wgh open 42  # open item 42 in the browser, mark it read (here and on GitHub)
wgh read 42  # mark item 42 read without opening
wgh stop     # stop the background poller (restarts next time you open wgh)
wgh version  # print the installed version

Interactive timeline

Run wgh in a terminal to open a full-screen timeline. When piped or redirected, it prints plain text so scripts keep working.

The window stays live. It re-reads its local data every couple of seconds, so anything the background poller picks up shows up on its own, and it refreshes on launch and when you press R. A ⟳ syncing marker in the title bar means a sync is in flight, and the footer shows whether the background poller is running. (If it isn't, the open window checks GitHub itself.)

Four tabs, each with a live count:

Tab	Shows
1 Inbox	unread items others put on you: review requests and assignments
2 My PRs	every open PR you own, with its latest activity or CI and merge state
3 Read	items you've already handled
4 CI	build pass or fail, and blocked or clean, on your tracked PRs

Key	Action
1-4, Tab	switch tab (Tab cycles)
↑/↓, k/j	move the selection
g / G	jump to newest / oldest
PgUp/PgDn	page by a screenful
⏎	open the selected item in the browser and mark it read
r	mark read without opening
R	check GitHub now
q / Esc / Ctrl-C	quit

Background poller

The first time you open wgh, it installs a small background service (a launchd agent named com.watchgh.poller) that runs wgh on its own. macOS keeps it alive across logins and reboots, so it checks GitHub every few minutes and sends desktop notifications even when no window is open.

Notifications are grouped by type into a running count of what needs you: "3 reviews requested", "2 PRs assigned to you", "2 PRs failing CI", "1 PR blocked", "2 PRs need your reply". You get one notification per type instead of one per event, and it only re-alerts when the count goes up. Open wgh to see the items, and the count clears as you handle them. The first check after starting is silent, so a cold start doesn't alert you about your whole backlog.

wgh stop   # stop the poller and remove its service
wgh        # opening wgh again reinstalls and starts it

For notifications, install terminal-notifier (brew install terminal-notifier) and each count updates its banner in place. Without it, wgh shows a single summary banner instead. The poller runs with a minimal environment, so it reads your token from gh auth token; make sure the GitHub CLI is signed in (gh auth login). Its log is at ~/Library/Application Support/watchgh/poller.log.

Configuration

An optional config.toml sits next to the data file (~/Library/Application Support/watchgh/config.toml). It's flat key = value, every key is optional, and a malformed file falls back to the defaults. See config.example.toml for the full list.

The poll interval controls how often the background poller checks GitHub. It defaults to 5m (minimum 60s). Desktop notifications pull you in and R refreshes on demand, so polling more often rarely pays for the extra traffic.

Data lives in a SQLite file at ~/Library/Application Support/watchgh/watchgh.db. Read items are removed after 30 days (set with retention); unread items are kept. PRs that merge or close drop out of every tab on the next check, so a finished PR never lingers in Read.

License

MIT. See LICENSE.