Drink water. Rest your eyes. Stretch.
Linux desktop app that fires customizable system notifications, tracks your daily progress, and serves a small web UI on localhost:8765 for CRUD and stats. The UI features a full-screen ambient scene (ocean depth, rain, sunset, forest, or night sky) with a glassmorphism panel on top. The product name "Courant" means current / flow in French — the gentle stream that nudges you toward healthier breaks.
- ✅ Phase 1 — Core CLI + desktop notifications working end-to-end
- ✅ Phase 2 — Functional web UI (FastAPI + HTMX)
- ✅ Phase 3 — Cozy aesthetic with ambient scenes (ocean, rain, sunset, forest, night)
- ✅ Phase 4 — systemd integration + PyPI publish + ambient audio
pipx install courant
courant install-scenes # ~10 MB of ambient videos
courant install-audio # ~2 MB of ambient sounds (optional)
courant install # creates a systemd user service (auto-starts at login)The web UI is at http://localhost:8765.
git clone https://github.com/BryanBradfo/courant
cd courant
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
courant install-scenes
courant start # foreground daemon
courant status # (in another terminal) see configured reminders
# Ctrl+C in the daemon terminal to stopOn first launch, three default reminders are seeded:
| Reminder | Interval | Tracking |
|---|---|---|
| Drink water | 45 min | Yes (8 glasses/day goal) |
| Eye break (20-20-20) | 20 min | No |
| Stretch | 90 min | No |
All reminders fire only between 09:00–18:00 on weekdays by default. You can customize all of this from the web UI at http://localhost:8765/reminders while the daemon is running, or directly in the SQLite database at ~/.local/share/courant/courant.db.
Courant uses 6 looping background videos (~10 MB total, re-encoded from larger originals) for the cozy aesthetic. They are not bundled in the repo — fetch them with :
courant install-scenes
Progress is shown per scene. Files land in ~/.local/share/courant/videos/. If some downloads fail, re-run the command — it skips already-installed scenes.
Until you install them, you'll see a fallback gradient background.
After courant start, point your browser at http://localhost:8765 :
- Dashboard — see each reminder's daily progress and click
+1to log a hit - Reminders — create / edit / disable / delete reminders
- Stats — daily progress per reminder
- Settings — global preferences (e.g. snooze duration)
Notifications fire on the desktop via D-Bus as configured. Clicking a notification action ("+1 glass" or "Snooze 10 min") records an event in the same database the web UI reads from — both views stay in sync.
Courant ships with 5 ambient scenes you can choose from in Settings :
| Scene | Vibe |
|---|---|
| Ocean depth | Bubbles rising through a deep-blue gradient |
| Rainy window | Diagonal rain streaks on a gray-blue sky with a warm glow indoors |
| Sunset beach | Orange-violet sky with animated waves |
| Forest stream | Autumn leaves falling through green god-rays |
| Calm night | Twinkling stars and a moon glow |
Want to add your own ? See docs/ADDING_A_SCENE.md.
pytest -vCurrently 84 tests covering models, SQLite repository, business logic, scheduler integration, the FastAPI web UI, and CLI smoke tests (including a subprocess test that verifies the daemon actually serves HTTP).
This is a phased build. See docs/superpowers/specs/ for the design spec (currently in French, English translation welcome) and docs/superpowers/plans/ for phase-by-phase implementation plans.
Contributions are welcome — especially:
- Translations of user-facing strings and design docs
- New ambient scenes (each scene is a self-contained Canvas module — see
docs/ADDING_A_SCENE.md) - Bug reports from running on non-GNOME desktops (Plasma, XFCE, Hyprland…)
MIT — see LICENSE.