ForgeWatch

Monitor your GitHub pull requests. Get notified instantly.

An async Python daemon that watches GitHub for PRs assigned to you, sends desktop notifications, and shows live status in your system tray.

---

Screenshots

Desktop notifications Individual notifications with author avatars and clickable links when new PRs arrive.	System tray indicator Live PR count in your panel with colour-coded status icons.
PR list popup Click the tray icon to see all your PRs at a glance. Click any PR to open it in your browser.	Setup wizard Interactive CLI walks you through configuration and systemd service setup.

---

Features

• Live PR monitoring -- polls the GitHub Search API for PRs assigned to you or requesting your review
• Desktop notifications -- individual notifications for small batches with author avatars and clickable links; summary for larger batches
• System tray indicator -- optional panel icon with live PR count, colour-coded status, and a popup window listing all PRs
• D-Bus interface -- query current PR state, trigger manual refresh, subscribe to change signals
• GitHub Enterprise support -- configurable API base URL for GHE instances
• Systemd integration -- runs as a user service with security hardening and systemctl reload support
• Resilient -- exponential backoff with configurable retries, rate limit handling, graceful shutdown (SIGTERM, SIGHUP for config reload)
• Runtime configurable -- log level, notification behaviour, D-Bus toggle, and more via config reload without restarting

---

Installation

From PyPI

# Using pip
pip install forgewatch

# Using pipx (recommended for CLI tools)
pipx install forgewatch

# Using uv
uv tool install forgewatch

From source

git clone https://github.com/dvoraj75/forgewatch.git
cd forgewatch
uv sync            # install runtime + dev dependencies

System packages (for the indicator)

The system tray indicator requires GTK3 and AppIndicator3:

# Ubuntu / Debian
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 \
    gir1.2-appindicator3-0.1 libcairo2-dev libgirepository1.0-dev

# Fedora
sudo dnf install python3-gobject gtk3 libappindicator-gtk3

The core daemon works without these -- the indicator is fully optional.

---

Quick start

1. Configure

The fastest way to get started is the setup wizard:

forgewatch setup

Or configure manually:

mkdir -p ~/.config/forgewatch
cp config.example.toml ~/.config/forgewatch/config.toml
$EDITOR ~/.config/forgewatch/config.toml

Minimal config:

github_token    = "ghp_your_personal_access_token"
github_username = "your-github-username"
poll_interval   = 300       # seconds (minimum 30)
repos           = []        # empty = all repos, or ["owner/repo1", "owner/repo2"]

The token can also be provided via the GITHUB_TOKEN environment variable. See docs/configuration.md for the full reference.

2. Run

forgewatch                          # start the daemon
forgewatch -v                       # verbose (DEBUG) logging
forgewatch -c /path/to/config.toml  # custom config path

3. Manage as a systemd service

forgewatch setup --service-only    # install + enable + start services
forgewatch service status          # check service status
forgewatch service restart         # restart after config changes

Or manually:

cp systemd/forgewatch.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now forgewatch
journalctl --user -u forgewatch -f  # follow logs

4. System tray indicator (optional)

forgewatch-indicator               # start (daemon must be running)
forgewatch-indicator -v            # verbose logging

As a systemd service:

cp systemd/forgewatch-indicator.service ~/.config/systemd/user/
systemctl --user enable --now forgewatch-indicator

See docs/systemd.md for the full service management guide.

CLI commands reference

forgewatch setup                    # interactive setup wizard
forgewatch setup --config-only      # only create config file
forgewatch setup --service-only     # only install + start services
forgewatch service status           # show service status
forgewatch service start|stop|restart
forgewatch service install          # install systemd unit files
forgewatch service enable|disable   # toggle autostart
forgewatch uninstall                # remove services + optionally config
forgewatch completions bash         # generate bash completions
forgewatch completions zsh          # generate zsh completions
forgewatch completions tcsh         # generate tcsh completions

---

Architecture

                         ┌──────────────┐
                         │  GitHub API  │
                         └──────┬───────┘
                                │
                       ┌────────▼────────┐
                       │     Poller      │
                       │  (aiohttp +     │
                       │   asyncio)      │
                       └────────┬────────┘
                                │
                       ┌────────▼────────┐
                       │   State Store   │
                       │   (in-memory)   │
                       └───┬─────────┬───┘
                           │         │
                  ┌────────▼──┐  ┌───▼──────────┐
                  │ Notifier  │  │    D-Bus     │
                  │ (notify-  │  │  Interface   │
                  │  send)    │  └───┬──────────┘
                  └───────────┘      │
                              D-Bus session bus
                                     │
                             ┌───────▼────────┐
                             │   Indicator    │
                             │  (GTK3 tray +  │
                             │   popup window)│
                             └────────────────┘

The poller queries the GitHub Search API on a configurable interval. The state store computes diffs (new / updated / closed PRs). The notifier sends desktop notifications for new PRs. The D-Bus interface lets the indicator (and other tools) query current state. The indicator is a separate process that shows a live tray icon and clickable PR list.

For the full design, see docs/architecture.md.

---

Development

uv sync                        # install all deps
uv run pytest                  # run tests (parallel, with coverage)
uv run ruff check .            # lint (all rules enabled)
uv run ruff format .           # format (black-compatible)
uv run mypy forgewatch         # type check (strict mode)

See docs/development.md for coding conventions, testing patterns, CI pipeline details, and project structure.

---

Documentation

Document	Description
Architecture	System design, component interactions, design decisions
Configuration	Full configuration reference with examples
Development	Developer guide: tooling, conventions, CI pipelines, testing
Systemd	Service setup, management, and troubleshooting

Module API references

Module	Description
CLI	Management subcommands (setup, service, uninstall, completions)
Config	Configuration loading and validation
Poller	GitHub API client, pagination, rate limiting
Store	In-memory state store with diff computation
D-Bus Service	D-Bus interface methods, signals, serialization
Notifier	Desktop notifications, avatars, click-to-open
URL Opener	XDG portal + xdg-open URL opener
Daemon	Main daemon loop and signal handling
Indicator	System tray icon, popup window, D-Bus client

---

Dependencies

Runtime:

Package	Purpose
aiohttp	Async HTTP client for GitHub API
dbus-next	Async D-Bus client/server
gbulb	GLib/asyncio event loop integration (for the system tray indicator)

System tray indicator (optional, requires system packages):

Package	Purpose
GTK3 + AppIndicator3	System packages (see Installation)

Dev-only: pytest, pytest-asyncio, pytest-xdist, pytest-cov, aioresponses, ruff, mypy, pre-commit, pip-audit.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, coding conventions, testing guidelines, and the PR process.

License

MIT -- see LICENSE for details.