One recurring reminder that counts from when you started it, and then actually interrupts you.
Set an interval. Groundhog sits in the tray counting it down. When it falls due the screen flashes and a sound plays for up to a minute, and then it keeps flashing silently until you dismiss it or snooze it. It does not queue up, it does not stack, and it does not fade away while you are looking at something else.
A recording of the Alert goes here.
Coming in a follow-up commit.
Every link below always points at the newest release. Nothing is signed, so your system will most likely ask you to confirm the first launch. The README says exactly which button to press on each platform.
The installer is per user: it needs no administrator rights and writes nothing to Program Files. The portable zip is one executable that runs from anywhere, including a USB stick.
Universal: Apple silicon and Intel in one bundle. Requires macOS 13 or newer.
The Linux build requires glibc 2.39 or newer, so it
does not run on Debian 12 or Ubuntu 22.04. Those ship 2.36 and 2.35. The .deb
declares the requirement and dpkg will refuse to install readably; the tarball has
nobody to declare it to, so the binary would simply die at exec. Check yours with
ldd --version.
Sound needs libasound.so.2. On a stock
PipeWire desktop you may need pipewire-alsa for the alert to be audible; the
.deb recommends it for you. Without it Groundhog still alerts, silently.
There are eight, and there will only ever be eight.
| Setting | What it does |
|---|---|
| Reminder | The words that appear on the alert. Up to 120 characters. Anything longer is trimmed. The default is Check the water bowl. |
| Remind me every | The interval, as hours and minutes. It is counted from when you started it, not from the top of the hour, so a 2 hour interval started at 09:17 falls due at 11:17. Minimum one minute, maximum 23 hours 59 minutes. Changing it restarts the countdown from now, so a shorter interval can never fire while you are still in the settings window. |
| How loudly | One of the three levels below. |
| Snooze length | How far snoozing pushes the reminder back, in minutes. 1 to 1440. Snoozing pushes the whole schedule back rather than inserting an extra reminder, there is no limit on how many times you may do it, and it never escalates: the fifth snooze is exactly like the first. |
| Play sound | Whether the alert makes a noise. The sound always stops after 60 seconds even if the alert is still on screen, and the volume is fixed per level rather than being a ninth setting. A machine with no audio device flashes silently and says so once. |
| Quiet hours | A window, given as HH:MM to HH:MM on a 24 hour clock, inside which
the countdown is frozen. It does not suppress a reminder that would have fallen
due; it stops the clock so nothing ever falls due in there at all. A window that crosses midnight
(22:00 to 07:00) works as you would expect. Set 22:00 to 07:00 with a 2 hour interval, and a
reminder that had 90 minutes left at 22:00 arrives at 08:30. |
| Start counting on launch | On, Groundhog starts its countdown the moment it opens. Off, it waits in the tray until you choose Start, so opening it does not commit you to anything. |
| Start Groundhog when I sign in | Creates a startup entry for your account. This checkbox is the only thing in the world that creates or removes it: the Windows installer deliberately has no such option, and the Debian package deliberately installs no autostart file. If you move a portable copy, launch it once and the entry repairs itself. |
| Level | What you get |
|---|---|
| Gentle | An ordinary window, roughly 700x400, on a warm static background. No flashing at all. It comes to the front, it has a title bar, and you can close it like any other window. One soft chime. |
| Normal | The whole screen, pulsing slowly between two ember tones once a second. The chime strikes again every 10 seconds until the 60 second cap. |
| Get Up | The whole screen, flashing red three times a second, with a continuous sound for the full 60 seconds. Three flashes per second is a hard ceiling: there is no setting that raises it and no value you can put in the settings file that gets past it, because faster than that is past the usual photosensitivity guidance. |
Both full-screen levels arm their buttons 500 milliseconds after appearing, so a click or a keypress already in flight cannot dismiss an alert you have not read yet. Enter dismisses, Escape snoozes.
Groundhog holds a reminder rather than firing it at a screen nobody is looking at, and delivers it about three seconds after you come back. How well it can tell that you left differs by platform, and where it cannot tell, it alerts: a reminder arriving at a locked screen is a much smaller failure than one that never arrives.
| Platform | Observed |
|---|---|
| Windows | Lock and unlock, display on and off, and suspend and resume. The full set. |
| macOS | Screens sleeping and waking, and system sleep and wake. Lock and unlock are read from two notification names Apple has never documented, so that half may simply not work; if it does not, Groundhog interrupts a locked screen rather than holding the reminder. |
| Linux | Lock and unlock, and suspend and resume, both through logind. There is no display-off half at all. No portable signal for a blanked screen exists across GNOME, KDE and the rest, so a display that went dark without locking does not hold a reminder. This is a decision, not an oversight. |
Time spent suspended counts toward the interval on all three platforms, so a machine that slept for three hours with a 2 hour interval reminds you shortly after it wakes rather than three hours later. A reminder that was held so long it outlived a whole interval expires quietly instead of arriving stale.
Groundhog lives in the tray. The tooltip names the state whenever it is not plainly counting down, including admitting to a reminder it missed. The menu has five items: Start, Snooze, I already checked it, Settings and Quit. Quit means quit: closing the settings window leaves Groundhog running, and quitting stops the countdown entirely rather than minimising anything.
On a desktop with no tray at all, most notably stock GNOME, Groundhog opens a small window of its own instead, every launch, carrying Settings and Quit. Installing a tray extension is what makes it go away, and its disappearance is how you know the extension worked.
Groundhog contacts the network exactly once, and only because you pressed Check for updates in the settings window. It downloads nothing and installs nothing; it asks GitHub which version is newest and tells you. There is no background check and no telemetry.
To hear about releases without pressing anything, either use Watch > Custom > Releases on the repository, or subscribe to the Atom feed at https://github.com/jparkerweb/groundhog/releases.atom.
One JSON file, in your account's configuration directory:
| Windows | %APPDATA%\Groundhog\settings.json |
| macOS | ~/Library/Application Support/Groundhog/settings.json |
| Linux | ~/.config/Groundhog/settings.json |
A corrupted file does not stop Groundhog. It starts on the defaults, tells you once, and carries on. So does a configuration directory it cannot write to: settings then last until you quit.