GitHub PR Watcher

A CLI tool that monitors GitHub pull requests across your local repositories. It discovers repos, lets you pick which contributors and branches to watch, and polls on an interval. You choose the watch mode -- just observe, auto-approve, auto-merge, or both.

Installation

npm install -g github-watch

Or run it directly without installing:

npx github-watch

Requires Node.js 18+ and the GitHub CLI (gh).

Quick Start

# Watch repos starting from the current directory
github-watch

# Watch all repos under a specific path
github-watch ~/Source/MyOrg

# Limit directory depth for repo discovery
github-watch -d 2 ~/Source

# Preview what would happen without taking action
github-watch --dry-run

# Skip all prompts using saved settings from last session
github-watch -y

# Clear saved settings and start fresh
github-watch --clear

What It Does

1. Verifies gh is installed and authenticated
2. Offers to restore saved settings from a previous session (if any exist)
3. Discovers git repos from your current directory (or a path you provide)
4. Presents interactive menus to select repos, target branches, and contributors
5. Lets you pick a watch mode: watch only, approve, merge, or approve and merge
6. Polls GitHub for open PRs on your chosen interval
7. Displays PRs in a clean, aligned terminal layout with color-coded status
8. Takes action on PRs based on the selected mode

Your selections (including the GitHub account, watch mode, and logging preference) can be saved and automatically restored on the next run. When saved settings exist, each menu pre-selects your previous choices so you can just hit Enter to confirm.

Options

| Flag | Short | Description | |---|---|---| | --path <path> | -p | Starting directory for repo discovery | | --dry-run | -t | Run without taking any actions on PRs | | --depth <n> | -d | Limit directory depth for repo discovery | | --clear | -c | Clear saved settings before starting | | --yes | -y | Auto-accept all saved settings without prompting |

The --yes flag requires saved settings to exist. If there are no saved settings, it has no effect and the interactive wizard runs normally.

Unknown options are rejected with an error and the usage text is displayed.

Watch Modes

The watch mode is selected through an interactive menu during setup:

| Mode | Behavior | |---|---| | Watch only | Display matching PRs each cycle, take no action | | Approve | Auto-approve pending PRs (skips your own) | | Merge | Auto-merge approved PRs that pass all checks | | Approve and merge | Both approve and merge in a single pass |

The selected mode is saved with your settings and pre-selected on the next run.

Documentation

See USAGE.md for the full walkthrough covering authentication, repo discovery, branch filtering, contributor selection, watch modes, the polling loop, and saved settings.

Tech Stack

• Node.js (ES modules)
• Commander.js for CLI parsing
• Chalk for terminal styling
• Custom interactive menus (no external prompting libraries)
• GitHub CLI (gh) for all GitHub operations

Contact

Have an idea, feature request, or bug report? Pull requests are always welcome, but if you'd rather just reach out directly, feel free to get in touch.

Fred Lackey [email protected] https://fredlackey.com