🧘 StretchBreak

A respectful stretch break reminder for people who forget to stand up. Lives in your system tray, counts your active time at the computer, and after 45 to 50 minutes takes over the screen with a 90 second guided stretch routine. Cross platform, macOS, Windows and Linux.

Built with Electron, React and Vite.

Why

Working from home makes it easy to sit through three hours without noticing. Notifications are too easy to ignore, and hard blocks feel hostile. StretchBreak sits in the middle, a full screen overlay with enough friction to make stretching the path of least resistance, and an escape hatch that is always one key away.

📖 Read the full UX Case Study, from a failed Oura ring alert to design principles and an ongoing two person diary study.

Features

• Activity based timer, not clock based. If you walk away for lunch, system idle detection resets the cycle. The app never asks you to stretch ten minutes after you came back from an hour away.
• Meeting aware. Detects active Zoom and Webex meetings by process heuristics and silently postpones the break until the call ends. A manual Do not disturb toggle in the tray covers browser based calls like Google Meet.
• Full screen break overlay on every connected display, with a countdown ring and a written home office friendly routine that rotates between breaks, neck, shoulders, walking, back, eyes and wrists.
• Snooze with memory. Snoozing waits 5 minutes and re checks for meetings before showing the overlay again.
• Escape hatch always available. Esc or the Skip button closes the break instantly, no guilt screens. Friction should persuade, never punish.
• Configurable interval from the tray, 30 to 90 minutes, persisted between sessions.

Development

Requires Node.js 20 or later.

npm install
npm run dev

npm run dev starts Electron with hot reload for the React overlay. The app appears in your system tray, there is no dock icon and no main window by design.

Tip for testing, set the work interval to 30 in the tray and lower workMinutes or TICK_SECONDS in src/main/index.js if you want breaks to fire quickly during development.

Building installers

npm run dist:mac     # .dmg
npm run dist:win     # .exe (NSIS installer)
npm run dist:linux   # AppImage

Note, building for Windows from macOS produces an unsigned installer. Test it on a real Windows machine.

Project structure

src/
├── main/index.js        → state machine, tray, idle + meeting detection, overlay windows
├── preload/index.js     → safe IPC bridge (contextBridge)
└── renderer/
    ├── index.html
    └── src/
        ├── main.jsx     → React bootstrap
        ├── App.jsx      → break overlay, countdown ring, routine, snooze and skip
        └── styles.css   → calm dark theme
resources/
└── trayTemplate.png     → menu bar icon (template image, adapts to light and dark)

How the state machine works

WORKING ──(45-50 min active)──▶ MEETING CHECK ──(free)──▶ BREAK OVERLAY
   ▲                                  │ (in a meeting or DND)      │
   │                                  ▼                            │
   │                            wait silently          snooze ─▶ SNOOZED
   │                                                       (5 min, back to check)
   └──── idle > 5 min resets the cycle ◀── done or skip ◀──┘

License

MIT