Rituals

macOSPythonFastAPIproductivitydesktop app
Source

Rituals is a tiny macOS 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.

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 a simple disk-backed JSON store, with one entry per ISO week so duplicates can’t sneak in.
  • 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.
  • Icon — the flat sunset is 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.

No account, no API keys, nothing to configure — your priorities and wins live only on your Mac, in ~/.rituals/data.json, and never leave it.

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.