Rituals

macOSweb appmobilePythonFastAPISupabaseproductivitydesktop app
Source

Rituals is a tiny app for the two weekly check-ins I could never keep up in a notes file: planning the week ahead and noticing what actually went well. It runs as a native macOS app and as a mobile-ready web app, so I can do both from my desk or my phone.

What it does

Two rituals, one quiet home for both:

  1. Sunday — set your top 3. Pick the three priorities that matter for the week ahead and check them off as you go. A progress ring fills as you complete them.
  2. Friday — capture a win. Write down one thing that went well. Small or large, it gets remembered.

Everything archives automatically, grouped by year and month, so your history stays browsable instead of turning into an endless list. A gentle “Due today” nudge appears on the right day, and you can edit this week’s priorities or win inline whenever you want.

How it’s built

  • Backend — FastAPI + uvicorn over Supabase (Postgres), with one row per ISO week so duplicates can’t sneak in and your history syncs across every Mac running the app.
  • Frontend — a single-page HTML/JS UI (Tailwind) with the week card, progress ring, and collapsible year/month archive.
  • Desktop shell — a Python entry point starts the server on a random local port in a background thread and opens it in a native macOS WKWebView window via pywebview. Packaged into a standalone .app with PyInstaller.
  • Web app — the same FastAPI server is deployed to a host (the UI is already mobile-responsive), so the exact same app opens in any phone browser. Because both the Mac app and the web app read the one Supabase database, they stay in sync automatically.
  • Icon — an amber sunrise generated from a small Pillow script, so it’s reproducible rather than hand-drawn.

Get it

The code is on GitHub — use the Source link above. Build the Mac app with:

git clone https://github.com/stephenhefekta/rituals.git
cd rituals
./build.sh        # produces dist/Rituals.app

Drag Rituals.app to your Applications folder. It isn’t notarised by Apple, so on first launch right-click it → Open → Open.

Your priorities and wins live in your own Supabase project, so the same history follows you across every Mac you run the app on. Drop your SUPABASE_URL and key into ~/.rituals/.env (the README walks through the one-time setup), and a second computer picks up right where the first left off.

Why I made it

The hard part of any ritual isn’t the doing, it’s the returning — week after week. I wanted something that made planning and reflecting feel like a thirty-second habit instead of a chore, and that quietly kept the receipts so I could look back and see the pattern. Turns out three priorities and one win is enough.