Skip to content

About

macOS menu bar app that counts work and rest time and reminds you to take a break

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Break Reminder

A tiny macOS menu bar app that counts how long you have been working without a pause and reminds you through Notification Center to take a break.

  • Work time is measured from system-wide keyboard, mouse and trackpad activity.

  • Rest starts after the input has been idle for 5 minutes (configurable). The work counter resets.

  • After 25 minutes of continuous work (configurable) a notification fires with a sound (Submarine by default), then repeats every 10 minutes until you rest.

  • Each reminder's headline is one concrete activity, like "Drink some water" or "Look out the window", picked from categories you can turn off (move, eyes, drink, air, breathe, people, enjoy, home, mac) plus your own lines such as medication. Each built-in one carries a one-line reason why it helps, worded to what research supports, which can be turned off. Never the same as the last two, outdoor ones only in daylight, coffee not after 16:00, "Dance" only while a music app is playing. Repeats keep the activity and shorten the text. Or use your own title and message.

  • The menu bar item is a heart by default, drawn as a gauge of the week's on-time share like the battery icon. The arc around it shows the block in the neutral tone; there are no state colors in this mode, the blink carries the warning. The arc is gone while you rest. Settings can switch it to a dot, or to the minute counter (23, or 1:05 from an hour on, optionally with the unit) wrapped by the outline. The default theme is monochrome: the number stays in the menu bar color and the outline carries the state, red only once you are over. The Signal theme adds orange for the warning and green for rest; Accent uses your macOS accent color.

  • A thin outline around the counter shows the block's progress. By default it grows from the bottom toward the top on both sides as time is spent, and a whole block covers half the outline (adjustable under Advanced, or with defaults write dev.vasyl.BreakReminder outlineSpanPercent -int 75). Settings offers time spent, time left or Off, with the direction under Advanced. Past the limit the arc stays at its covered share and turns red; it never closes into a full ring.

  • The item beats like a heart, a lub-dub at a configurable rate: during the warning it climbs from the normal rate (10 bpm) to the warning rate (40), and holds at the over rate (80) past the limit. Beating while working is on by default and can be turned off. In Heart mode you choose which parts beat: the body, the level, the arc, any combination; by default only the body beats. Rates are in Settings › Appearance › Advanced or defaults write dev.vasyl.BreakReminder beatWarningBPM -int 120. With Reduce Motion on it steps instead of fading. Increase Contrast thickens the outline.

  • Smart Pause holds reminders, sound and blink while the camera or microphone is in use, while the screen is shared (Zoom and macOS recording), or while a fullscreen app is in front (off by default). Each trigger is a toggle. Focus modes are not detected since macOS reveals them only to apps with Full Disk Access. A break that comes due during the pause is delivered the moment the pause ends, as "Call over · Walk a little", even at Gentle and whatever the repeat interval; an optional wait of up to 15 minutes can delay it.

  • Stats, the first tab of the window (⌘S from the menu): a one-line headline, then today as a timeline of focus and rest with skipped breaks marked, the week as bars of focused time, or the month as a calendar grid tinted by on-time share. Below, the figures with deltas against the previous period: focused, resting, longest block, breaks taken, on time, streak. An optional heart next to the counter fills with the week's on-time share. A break is on time when a rest starts within 5 minutes of the limit, half when within 15. Breaks held by Smart Pause are not counted against you. History lives in ~/Library/Application Support/BreakReminder/history.json: daily totals for 62 days and break events for 14 days, older data is dropped automatically.

  • Firmness. Gentle sends one reminder per block with no repeats, and the heart keeps its calm beat without the warning ramp or the fast beat over the limit; Normal repeats on your interval and blinks in the warning; Firm repeats every 5 minutes. Automatic, the default, earns calm from the last 7 days: 90% on time means Gentle, 40 to 89 Normal, 15 to 39 Firm. Below 15 the app steps down to Gentle and asks once, through a notification with Pause for Today and Change Limit buttons, instead of nagging. Re-evaluated daily once 5 breaks were due. Pick a level in Settings to lock it.

  • The arc is a recovery gauge. It fills with work and unwinds from the first idle seconds, at a rate where the rest the block deserves brings it to empty; the heartbeat keeps going until it is. Return before the threshold and the block continues with the arc back at the work level. With "Carry unfinished rest into the next block" on, a longer block needs a proportionally longer rest and whatever was not recovered starts the next block's arc. Reminders and the limit are unaffected.

  • Updates. Once a day the app checks the latest GitHub release. With Homebrew installs it upgrades itself through brew upgrade at the next rest and restarts in the same state; the menu shows "Update to x.y.z…" to do it right away. Both are toggles in Settings › General. Copies not installed with Homebrew get a link to the release page.

No Accessibility or Input Monitoring permission is needed. The app only reads the system idle time (CGEventSource.secondsSinceLastEventType), never individual keystrokes or pointer events. The only prompt you will see is the standard notification permission dialog on first launch.

Requirements

  • macOS 13 or newer
  • Xcode (or the Command Line Tools) for the Swift toolchain

Install with Homebrew

brew install vasylherman/tap/break-reminder
open "$(brew --prefix)/opt/break-reminder/BreakReminder.app"

Homebrew builds the app from source on your Mac, so no notarization or Gatekeeper override is needed. To start it at login either use the in-app toggle or brew services start break-reminder. The service also restarts the app after a crash (not after a normal Quit); the in-app login item cannot, since launchd only supervises agents of apps signed with a Developer ID.

Feedback

Use Feedback in the app menu: "Request a Feature…" and "Report a Bug…" open GitHub issue forms with the environment details already filled in. Or open an issue directly on GitHub.

Build and run

./build.sh run       # build, assemble dist/BreakReminder.app and launch it
./build.sh install   # same, but copy the bundle to /Applications and launch from there
./build.sh bundle    # just build the .app bundle into dist/

Use install if you want "Launch at Login" to work: macOS registers login items by the app's location, so the bundle has to live somewhere permanent.

The bundle is ad-hoc signed, which is enough for local use. Nothing is uploaded anywhere.

Menu

Item What it does
Working for / Resting for Current counter and the configured limit
Breaks this week Breaks taken of breaks due in the calendar week
Firmness Current level and whether it is earned, stepped down or locked
Last work block / Last rest Length of the previous period, for a quick sanity check
Reset Work Timer Start the current work block from zero. A pending break counts as skipped
Stats… Opens the window on the Stats tab (⌘S)
Break Reminder x.y.z Installed version, also first in the menu bar tooltip
Pause Reminders Silence reminders for 30 minutes, 1 hour, 2 hours or until tomorrow. The counter keeps running. A Resume item appears while paused
Work Limit 25, 30, 45, 60, 90 minutes, or Custom… which opens Settings
Rest Counts After Idle 2, 3, 5, 10 minutes, or Custom… which opens Settings
Settings… Opens the window on the General tab (⌘,)
Feedback Request a Feature and Report a Bug open prefilled GitHub issue forms with your app version, macOS version, install method, settings and current state. Also links to Release Notes and the project page

Settings

Tab Options
General Launch at login, on by default for an installed copy. Daily update check and automatic install while resting. Work limit, rest threshold and warn-before minutes as steppers
Appearance Live preview, theme (Quiet, Signal, Accent), show as (minutes with unit, minutes, dot, heart), outline mode, weekly score heart beside it, and under Advanced the outline direction and blink
Reminders Firmness (Automatic, Gentle, Normal, Firm), repeat interval, optional prefix for the title, suggested activities with category toggles and the reason why, sound picker that previews on change, a chime when the rest is complete (Bottle by default, can be silent), Send Test Notification
Smart Pause Master switch, the three triggers with a live "Now" indicator when detected, and the grace period
About Version, install method, feedback and project links, copy the Homebrew install command, Reset All Settings

Settings are stored in UserDefaults under dev.vasyl.BreakReminder and apply immediately. For development, open BreakReminder.app --args --settings opens the window at launch.

How it decides work vs rest

Every 5 seconds the app reads the system idle time.

  • While working, an idle time at or above the rest threshold switches to resting. The rest is back-dated to the last input event, so the counter is accurate even though it is noticed late.
  • While resting, any new input switches back to working and starts a fresh work block.
  • Short pauses below the threshold (reading, thinking, a quick chat) stay inside the work block.
  • Sleeping the Mac counts as idle, so a closed lid long enough becomes a rest automatically.
  • State is saved every few seconds. If the app restarts (upgrade, crash, relaunch) within the rest threshold, the running work block and the pending reminder continue where they were. After a longer gap the current block starts fresh, but the last work and rest history is kept.

Layout

Sources/BreakReminder/
  main.swift             app entry point, menu-bar-only activation policy
  AppDelegate.swift      status item, menu, polling, reminder logic
  ActivityTracker.swift  work/rest state machine on top of system idle time
  Notifier.swift         Notification Center banners (osascript fallback for `swift run`)
  BreakActivities.swift  suggested break activities and the picking rules
  SmartPause.swift       call, screen share and fullscreen detection
  Updater.swift          daily release check and Homebrew self-update
  Firmness.swift         firmness levels and the automatic mapping from the weekly score
  History.swift          on-disk daily totals and break events with retention
  Stats.swift            day, week and month aggregation
  StatsView.swift        Stats pane
  Settings.swift         UserDefaults-backed options
  SettingsView.swift     SwiftUI settings panes (General, Appearance, Reminders, Smart Pause, About)
  SettingsWindowController.swift  one window with Stats first, then the settings panes
  Theme.swift            curated menu bar color themes
  MenuBarPreview.swift   animated preview of the menu bar item
  ProgressBorder.swift   outline layer around the counter
  SettingsWindowController.swift  hosts the form in an AppKit window
  Feedback.swift         GitHub links and prefilled issue forms
Support/Info.plist       bundle metadata (LSUIElement hides the Dock icon)
Support/Assets.car, AppIcon.icns  app icon (asset catalog for Notification Center, icns for Finder);
                         regenerate with Support/make-icon.swift, needs Xcode's actool
build.sh                 build, bundle, run, install

License

MIT

About

macOS menu bar app that counts work and rest time and reminds you to take a break

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages