Stall Watcher

Stall Watcher is a small passive Windows desktop app that monitors a selected screen region and sends a notification when that region stays visually still for a configured duration.

It only uses local screenshots and image comparison. It does not click, type, inject code, read another process memory, or interact with the watched application.

Install

Requires Python 3.12+.

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

Configure ntfy

Copy .env.example to .env and fill in your own values:

NTFY_URL=https://your.ntfy.server
NTFY_TOPIC=stall-watcher
NTFY_TOKEN=your-token

The .env file is only for ntfy secrets. App preferences are stored separately with Qt settings.

Run

From the repository root:

python -m src.main

Use

1. Select the monitor to watch.
2. Click Select region.
3. Drag a rectangle over the area to monitor. Press Escape to cancel.
4. Adjust capture interval, alert delay, and movement threshold.
5. Enable Windows and/or ntfy notifications.
6. Click Start monitoring.

The live motion score helps calibrate the threshold. For example, if motion is around 8.4 while moving and 0.7 while stopped, a threshold around 2.0 is a reasonable starting point.

Build a Windows exe

Install PyInstaller in your virtualenv:

pip install pyinstaller
pyinstaller --noconsole --name StallWatcher --paths . src/main.py

The executable will be created under dist/.

Development

Run tests:

pytest

The detector tests cover motion scoring, still-time accumulation, reset on movement, one alert per still period, and rearming after movement resumes.