Public beta · Apple Silicon · macOS 14+
Download the DMG from GitHub Releases. This beta is not Developer ID-signed or notarized; read the installation instructions for the first-launch security prompt.
A quiet native macOS menu bar app that provides a visual breathing rhythm while you work. SwiftUI controls, AppKit overlays, no dependencies. Requires macOS 14 or newer.
./scripts/build-app.sh
open "dist/Box Breathing.app"You can also drag the app into Applications. It lives in the menu bar as a breathing-profile icon, with no Dock icon. Click the profile icon for a standard macOS menu with Start/Pause, techniques, cue toggles, Settings, and Quit. Command-drag the icon to reposition it in the menu bar. Settings opens in a movable native window below the menu bar and notch. Close Settings with the red close button, Done, Escape, or Command-W; breathing continues. Click outside the menu or press Escape to dismiss it.
- Screen aura: a soft outline grows brighter with each inhale and fades on exhale.
- Floating orb: a small expanding sphere. Drag it at any time during a session. Its position is saved immediately and retained across settings changes, pause/resume, and app relaunch.
- Breathing lights: a centered row of soft blue lights fills outward on inhale and recedes on exhale. It stays faintly visible between breaths, independently of the aura.
- Cues can be combined. Aura and breathing lights always let clicks pass through. The orb accepts dragging without taking keyboard focus.
- Use Presence to adjust intensity and All displays for screen-edge cues on every connected display. Otherwise, edge cues use the primary display; the orb can be dragged to any display.
The cues use restrained macOS system blue and indigo colors with a subtle glow.
| Rhythm | Inhale | Hold | Exhale | Rest |
|---|---|---|---|---|
| Easy breathing (default) | 3 s | — | 4 s | — |
| Long exhale | 3 s | — | 6 s | — |
| Equal breathing | 4 s | — | 4 s | — |
| Box breathing | 4 s | 4 s | 4 s | 4 s |
Pace multiplies these durations. Slower 1.5× turns a 4-second phase into 6 seconds. Continuous sessions run until paused; timed sessions stop automatically. Every new session begins with an inhale. Sleep and lock temporarily hide the cues. Active sessions resume on wake/unlock with a fresh inhale and retain their remaining active session time. Manual pauses and completed timed sessions remain stopped. The app restores an active session when relaunched. Delayed timer callbacks recover instead of permanently stopping the cue.
Use the rhythm as a gentle cue, at a comfortable depth and pace. No-hold breathing is the default because the original aim is to interrupt unintentional holding. These presets are adjustable pacing patterns, not a personalized treatment or breath-detection system. The NHS breathing guidance advises comfortable breathing without forcing it.
swift build
./scripts/test.sh
./scripts/test-overlays.sh
./scripts/test-lifecycle.sh
mkdir -p dist
.build/debug/BoxBreathing --snapshot--snapshot renders the control panel to dist/preview.png and exits. The app uses a monotonic clock for breath timing. The frame timer only runs during a session. Nonactivating panels avoid taking keyboard focus, and ignoresMouseEvents allows working through the overlays.
- Keyboard backlight control is not implemented; hardware support needs a separate investigation.
- No automatic breath detection, audio, or scheduled reminders yet.
- The local build is ad-hoc signed for this Mac, not notarized for distribution. The build targets the architecture of the machine compiling it.
- Full-screen/Space behavior and external displays use standard AppKit panel options but need hands-on verification on your display setup. Some system windows can cover the cues.
AppKit references: mouse-event passthrough, full-screen auxiliary panels.
The product name is Box Breathing. Planned search topics include box breath, breathing exercise, breathwork, and the 4-7-8 breathing method. See the content plan.
The bundle identifier remains local.breathingroom.app to preserve existing macOS preferences through the rename. All displayed app names, executable names, and source targets use Box Breathing.
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0-only).
Enable Open at login in Settings to register with macOS. If approval is needed, the app provides a link to Login Items. Registration errors are shown rather than silently treating registration as successful. macOS remains the source of truth for this setting.
For local development, install the built app into a stable location before registering:
mkdir -p "$HOME/Applications"
ditto "dist/Box Breathing.app" "$HOME/Applications/Box Breathing.app"
"$HOME/Applications/Box Breathing.app/Contents/MacOS/BoxBreathing" --configure-login
open "$HOME/Applications/Box Breathing.app" --args --start--start explicitly starts a session once. Future launches restore the last active/paused intent. Quit stops the process but retains intent for the next launch; Pause clears it. Closing Settings leaves the cue running. Active sessions use a process activity assertion to avoid App Nap while still permitting system sleep.
The app listens for workspace sleep, display sleep, and session changes. Lock/unlock distributed notifications supplement those public workspace notifications; they are not a documented public API and may change in future macOS releases. Automated tests exercise the state transitions; a physical lock/unlock and reboot remain useful release checks.
Approved identity: F — Quiet Exhale, a female profile with a gentle exhale. Brand guide and asset index. The app build includes the exported app icon and a monochrome menu bar template.
Run ./scripts/package-dmg.sh on an Apple Silicon Mac. It builds the app and creates an ad-hoc-signed DMG with an Applications shortcut, installation instructions, the license, and a SHA256SUMS.txt file in dist/. Generated binaries remain excluded from Git; upload them as GitHub Release assets. Beta release notes.