💧 Sip Water Buddy

A hero and a pet that remind you to drink water, and anything else you tell them to.

Sip is a small desktop companion. A 3D hero (and a pet) walk onto your screen when a reminder is due, do a bit of showing off, and stay until you answer. Water is built in; add any other reminder you like, with dates and times. It is free, open source, and never connects to the internet.

Website: https://vicky-co.github.io/sip-water-buddy/

Characters	Reminders	On your desktop

Features

• Water reminder with your own interval and daily goal. Turn it off if you only want other reminders.
• Any reminder you like: one-time (date and time), every day, certain days of the week, or every N minutes/hours. Quick-add chips (In 10 min, In 1 hour, Tomorrow 9:00) make the common case a two-second job. Answer with Done, +10 min, +1 hour or Skip; pause, edit, test or delete from Settings.
• A hero and a pet: name them, choose who shows up (both, hero only or pet only; they are never both hidden), and pick their looks. Bring your own 3D avatar or pet (.glb), and your own pet sounds.
• Plays along: fetch (click anywhere on any screen), pet tricks, dance moves, sounds and music, all generated or bundled.
• A real Settings window (Characters, Reminders, Sounds, General), light and dark themes, keyboard accessible.
• Multi-monitor: the characters walk across all your screens.
• Message with them: the question appears the moment they land and follows them while they walk, so you can answer at once. Hover the mouse over them and they stop; move it away and they carry on.
• You decide how long they linger after you answer (right away, quick, normal, or 1-60 seconds in Settings → General), and the goodbye message has a ⏩ Go now button to send them off immediately.
• Wait where you want: tap 📍 Wait here in their message and click anywhere on any screen; they walk there and wait. 📌 Always wait here (or Settings → General) makes them use that spot every time instead of a random place; 🚶 Roam again undoes it.
• To-do list (switch it on or off in Settings → General): add items in the To-dos tab, tick them off, clear the finished ones. The tray menu has Show todos (with how many are open) and Quick add todo…, a tiny window to jot one down without opening Settings.
• Deadlines and reminders for to-dos: give a to-do an optional deadline (a date, and a time if you like). The hero and pet remind you before it, with a global "remind me N minutes before" setting that each to-do can override (or switch off). Overdue to-dos are marked in red in the list and in the tray menu.
• Your to-dos on the desktop: tray → Show todos makes the hero and pet appear, standing still, holding your list. Tick items off right there, and drag them anywhere; Sip remembers where you left them.
• Today: a tab listing every check-in the characters made today (water, reminders, to-dos) and how you answered (done, skipped, not yet). Tapped the wrong button? Change the answer; Sip asks you to confirm first and keeps your glass count and skip totals in step.
• Only ask during certain hours (Settings → Reminders → Water): choose a start and an end. Outside them Sip stays quiet, after the end the next ask is reset to the start, and changing the hours later (a longer window, an earlier start) takes effect straight away. Windows that run past midnight work too.
• Last 30 days at a glance (Settings → Stats): glasses per day against your goal, how far above or below the goal each day was, and how many check-ins and how many minutes you skipped, with a table of the exact numbers. History starts the day you update; it stays on your computer.
• Uninstall from inside the app: Settings → General → Uninstall Sip completely… (or the tray menu). It lists exactly what it will delete and asks first.
• Private and safe by design: no network, no telemetry, strict sandboxing (see SECURITY.md).

Download and install

Grab the latest build from the Releases page.

Windows 10 / 11 (64-bit)

1. Download Sip-Water-Buddy-Setup-<version>.exe from the release.
2. Double-click it. If Windows says it "protected your PC", choose More info → Run anyway (the app is not code-signed yet).
3. Sip installs for your user only (no administrator rights), adds Start menu and desktop shortcuts, and starts. Look for the water-drop icon near the clock (click the ^ arrow if hidden) and double-click it to open Settings.

It keeps running when you close any terminal, and starts when you sign in (switchable in Settings). Uninstall from Settings → Apps → Sip Water Buddy; your reminders and settings stay in %APPDATA%\sip-water-buddy (delete that folder to remove them too).

Prefer no installer? Download Sip-Water-Buddy-<version>-portable.exe: a single file you can run from anywhere (it starts a little slower).

Windows without an installer or unsigned .exe (blocked PCs)

Some PCs block downloaded programs from an "unknown publisher". Sip is unsigned, so use one of these folder options instead:

1. Run straight from the project folder (best when .exe downloads are blocked). Install Node.js 20+ (LTS), then either Code → Download ZIP on this page and extract it, or git clone https://github.com/vicky-co/sip-water-buddy. Double-click Start Sip (Windows, from folder).bat in that folder. The first run sets itself up (internet needed, about a minute); after that it starts at once. Nothing is installed and no downloaded .exe is run: Node.js fetches the Electron runtime itself. Or type npm install then npm start in a terminal.
2. Prebuilt folder. Download sip-water-buddy-<version>-windows-x64.zip from the release, right-click it → Properties → tick Unblock → OK, then Extract All and double-click Start Sip.bat (or Sip Water Buddy.exe). No installation and no Node.js needed. Delete the folder to remove it.

Group policies that block all unsigned programs (for example AppLocker) can still stop either route; ask the PC's administrator to allow the folder. Windows support is newer and has had less testing than Linux: please report anything odd.

Ubuntu / Linux

unzip sip-water-buddy-<version>-linux.zip && cd sip-water-buddy && ./install.sh

Needs Node.js 20+ (the installer offers to install it) and internet once, to fetch the Electron runtime. Look for the water-drop icon in the top bar. Tested on Ubuntu 24.04 (GNOME); Sip runs through XWayland so it can stay on top.

Uninstall completely

Easiest, on any system: open Sip's Settings → General → Uninstall Sip completely… (also in the tray menu). It shows exactly what will be deleted (the program or folder it runs from, shortcuts, start-at-sign-in entry, your reminders and settings, logs), asks you to confirm, then quits and removes it. If you ran Sip from a project folder (npm start or the .bat file), that folder is deleted too, so move out anything you want to keep first. The manual steps below do the same without opening the app.

Windows (installer): Settings → Apps → Installed apps → Sip Water Buddy → Uninstall. Then delete %APPDATA%\sip-water-buddy to remove your reminders and settings. Portable exe: quit Sip from the tray icon, delete the .exe, and delete %APPDATA%\sip-water-buddy. Windows (zip with Install.bat): run Uninstall.bat; it removes the program, shortcuts, start-at-sign-in and your data.

Ubuntu / Linux: run the uninstaller that was installed with Sip:

~/.local/share/sip-water-buddy/uninstall.sh          # asks first, then removes everything
~/.local/share/sip-water-buddy/uninstall.sh --keep-data   # keep your reminders and settings

It stops Sip and deletes the program, the app-grid launcher, the start-at-sign-in entry, your data and the logs. It only touches your home folder. If you no longer have the script, remove these by hand after choosing Quit from the tray icon:

pkill -f "electron.*sip-water-buddy"
rm -rf ~/.local/share/sip-water-buddy ~/.config/sip-water-buddy ~/.cache/sip-water-buddy.log \
       ~/.local/share/applications/sip-water-buddy.desktop ~/.config/autostart/sip-water-buddy.desktop

(Sip only installs Node.js if you let install.sh do it; remove that separately with sudo apt remove nodejs npm if you want.)

macOS is not packaged or tested. The code avoids platform-specific assumptions, so running from source may work; contributions welcome.

A two-minute tour

1. Open Settings (double-click the tray icon, or tray → Open Settings…).
2. Characters: give your hero and pet names; choose Hero and pet, Hero only or Pet only.
3. Reminders: type Stand up and stretch, tap In 30 min. Or choose Certain days, pick Mon-Fri, set 09:00, Add reminder.
4. When a reminder is due, the characters appear, say it, and wait. Done ✓, +10 min, +1 hour or Skip.
5. Sounds: pick a pet sound with ▶ Play, or add your own.

Your data and privacy

• Settings, reminders and added files live in your user profile with owner-only permissions: Linux ~/.config/sip-water-buddy/, Windows %APPDATA%\sip-water-buddy\.
• Sip makes no network requests; the app blocks them outright. The only time anything leaves the app is when you click a link in Settings (GitHub, LinkedIn, bug reports), which opens your normal browser.
• Models and sounds you add are checked, copied into Sip's own folder, and only ever read.
• Logs (for troubleshooting) are in the same folder as sip.log; Settings → General → Open log file.

Build and run from source

Requires Node.js 20+ (22 recommended).

git clone https://github.com/vicky-co/sip-water-buddy.git
cd sip-water-buddy
npm ci            # installs dev tools and builds the 3D bundle
npm start         # downloads the Electron runtime on first run, then launches Sip

Command	What it does
npm start	Run from source (adds --no-sandbox on Linux only)
npm test	Unit tests for settings validation and reminder scheduling
npm run lint	Syntax check of every script
npm run test:e2e	Launches the real app under a virtual display and drives both windows (Linux, needs xvfb)
npm run package:linux	Builds the Linux zip into dist/
npm run package:win	Builds the Windows installer and portable exe into dist/installer/ (run it on Windows; GitHub Actions does this for releases)

Project structure

sip-water-buddy/
├── src/
│   ├── main/            Main process: windows, tray, scheduler, validated IPC (main.js, branding.js)
│   ├── preload/         The only bridges between the windows and the main process
│   ├── shared/          core.js: settings validation + reminder scheduling (pure, fully unit-tested)
│   └── renderer/
│       ├── overlay/     The hero and pet window (3D rendering, animation, sound)
│       ├── settings/    The Settings window
│       └── vendor/      Generated three.js bundle (not committed; built by `npm ci`)
├── assets/              Icons, 3D models, sounds (provenance in assets/README.md)
├── scripts/             Build, packaging and installer scripts (linux/, windows/)
├── tests/               Unit tests and the end-to-end test
├── docs/                Architecture, adding characters, releasing, screenshots
└── .github/             CI, release automation, issue and PR templates

More detail: docs/ARCHITECTURE.md · docs/ADDING-CHARACTERS.md · docs/RELEASING.md

Troubleshooting

• Black box instead of a see-through background: start Sip with --no-gpu (Windows: right-click the shortcut → Properties → add --no-gpu at the end of Target; Linux: SIP_NO_GPU=1).
• No 3D hero or pet (cartoon only): Settings → General → Status shows why. Graphics acceleration problems fall back to software 3D.
• Nothing happens at the reminder time: Settings → Reminders shows each reminder's next time; use Test to preview one.
• Anything else: Settings → General → Open log file, then open an issue with the log.

Contributing

Bug reports, ideas and pull requests are welcome. Please read CONTRIBUTING.md first; it is short. Security problems: see SECURITY.md and report them privately.

Credits and licence

Made by Paresh Sethy: GitHub @vicky-co · LinkedIn. If Sip helps you, a ⭐ on the repository is the nicest thank-you, and connecting on LinkedIn is always welcome.

The code is released under the MIT licence. Third-party software and the 3D models and sounds have their own terms: see THIRD_PARTY_NOTICES.md and assets/README.md.