EyeBreak is a macOS menu bar app that helps reduce digital eye strain by reminding you to take regular breaks following the 20-20-20 rule.
Every 20 minutes, look at something 20 feet away for 20 seconds. This simple technique helps reduce eye strain, headaches, and fatigue from prolonged screen use.
Yes! The source code is provided under MIT License. You can use, modify, and distribute it freely.
No. EyeBreak collects zero data. All statistics are stored locally on your Mac. There's no analytics, no tracking, and no internet connection required.
- Open the Xcode project
- Select your development team
- Press ⌘R to build and run
- The app will appear in your menu bar
For detailed instructions, see QUICKSTART.md.
macOS 14.0 (Sonoma) or later. The app is built with the latest Swift and SwiftUI features.
Currently yes, as this is the source code version. You can build it once and then run the .app file without Xcode.
The minimum deployment target is macOS 14.0. To support older versions, you'd need to:
- Change deployment target in Xcode
- Replace MenuBarExtra with NSStatusItem
- Conditionally compile Charts (macOS 13+)
- Notifications: To send break reminders
- Screen Recording: To blur your screen during breaks
No. If you don't grant it, the app will use "Notification Only" mode instead of screen blur.
- Go to System Settings
- Privacy & Security > Screen Recording
- Enable the checkbox next to EyeBreak
- Restart the app
Yes. EyeBreak only uses this permission to create a blur overlay. It never actually records or saves your screen content.
- Click the eye icon in your menu bar
- Click "Start Timer"
- Work normally for 20 minutes
- Take your break when notified
Yes! Click the eye icon > Settings, then adjust:
- Work interval (10-60 minutes)
- Break duration (10-60 seconds)
- Pre-break warning time
Pomodoro is a time management technique: 25 minutes of work followed by a 5-minute break. Enable it in Settings > Session Type.
Yes, press ESC or click anywhere during the break. However, we don't recommend it—your eyes need the rest!
Yes! If idle detection is enabled (default), the timer automatically pauses after 5 minutes of no activity and resumes when you return.
Absolutely! Click the eye icon and press "Take Break Now" anytime.
Blur Screen (default)
- Blurs your entire screen
- Shows motivational message
- Forces you to look away
Notification Only
- Just sends a notification
- No screen blur
- Good for presentations/meetings
Eye Exercise
- Guided eye movement instructions
- Helps exercise eye muscles
- Educational approach
Settings > Break Style > Choose your preference
Yes! The blur overlay appears on all connected displays.
- Breaks completed today
- Breaks skipped today
- Total break time
- 7-day or 30-day history
- Daily goal progress
- Current streak
Click the eye icon > Settings > Statistics tab
Not currently, but this could be added as a future feature. All data is stored in UserDefaults.
Settings > Statistics > Reset Statistics button (bottom of the page)
This is intentional! EyeBreak is a menu bar app only. It's designed to be unobtrusive. The LSUIElement setting in Info.plist hides it from the Dock.
Very little. The app uses minimal CPU (<1% when idle) and has low memory footprint (~30-50MB). Battery impact is negligible.
The blur overlay should work with most apps. However, some full-screen games or apps with elevated privileges might prevent the overlay from appearing.
Yes! Build it on each Mac or copy the .app file. Settings are stored locally on each Mac.
No. It only takes action during breaks. The pre-break warning gives you 30 seconds to finish what you're doing.
- Check Activity Monitor - is EyeBreak running?
- Check if your menu bar is full (macOS hides icons when space is limited)
- Try quitting and restarting the app
- Grant Screen Recording permission in System Settings
- Restart the app after granting permission
- Try "Notification Only" mode if permission issues persist
- Check System Settings > Notifications > EyeBreak
- Ensure "Allow Notifications" is enabled
- Try different alert styles (Banners or Alerts)
- Check that Idle Detection is enabled in Settings
- Adjust the idle threshold (default: 5 minutes)
- Try moving your mouse after being idle
- Check Console app for error messages
- Ensure you're running macOS 14.0 or later
- Try cleaning build folder (⌘⇧K in Xcode)
- Delete DerivedData and rebuild
You need to complete at least one break for statistics to appear. Take your first break to populate the data!
This is normal for development builds. App icons are optional for menu bar apps since they primarily show in the menu bar.
The icon is defined in MenuBarView.swift. You can change it to any SF Symbol or custom image.
Currently no, but you can edit them in BreakOverlayView.swift. This could be a future settings option.
The app uses system sounds. You could add custom sounds by:
- Adding sound files to Resources
- Using AVAudioPlayer instead of NSSound
- Adding a sound picker in Settings
Yes! The app uses system colors but you can customize them in the SwiftUI views. Look for .foregroundStyle() and .background() modifiers.
Absolutely! The code is open source under MIT License. Fork it, make improvements, and share back.
- Swift 5.9+
- SwiftUI for UI
- Combine for state management
- IOKit for idle detection
- UserNotifications for alerts
- AppKit for window management
- Fork the repository
- Create a new branch
- Implement your feature
- Test thoroughly
- Submit a pull request
Create an issue on GitHub with:
- macOS version
- Xcode version
- Steps to reproduce
- Expected vs actual behavior
- Screenshots if relevant
Yes! The MIT License allows commercial use. You can build upon this code and sell your version.
Option 1: Share the source code (they build it themselves) Option 2: Archive and export as Developer ID app (requires paid Apple Developer account) Option 3: Submit to App Store (requires icons and Apple Developer account)
- For local use: No, free Apple ID works
- For sharing: Yes, you need Developer ID ($99/year)
- For App Store: Yes, required ($99/year)
- Design proper app icons (see ICON_GUIDE.md)
- Update bundle identifier to your domain
- Add screenshots and app description
- Archive and upload to App Store Connect
- Submit for review
Yes! The MIT License allows commercial use. Suggested pricing: Free, $2.99, or $4.99.
No. The app is sandboxed and only accesses UserDefaults for settings storage.
Yes. All statistics are stored locally in UserDefaults on your Mac. Nothing is sent anywhere.
No. The app works completely offline.
Yes. The code is open source—you can review it yourself. No network calls, no data collection, no hidden features.
vs. Time Out
- Modern SwiftUI interface
- Open source
- Privacy-focused
vs. Stretchly
- Native macOS app (not Electron)
- Better performance
- macOS-specific features
vs. LookAway
- Open source alternative
- Free to use and modify
- Active development
Potential future enhancements:
- Launch at login
- iCloud sync for settings
- Customizable break messages
- Break exercise videos
- Calendar integration
- HealthKit integration
- Shortcuts support
This depends on community feedback and contributions. Focus areas:
- Enhanced statistics
- More break styles
- Better accessibility
- Performance improvements
Yes! Create an issue on GitHub describing:
- The feature you want
- Why it would be useful
- How it might work
- Read the documentation (README, QUICKSTART, BUILD)
- Check this FAQ
- Search existing GitHub issues
- Create a new issue if needed
- ⭐️ Star the repository
- 🐛 Report bugs
- 💡 Suggest features
- 🔀 Contribute code
- 📢 Share with others
- ☕️ Buy the developer a coffee (if donation links provided)
Start one! Share your experience, help others, contribute improvements. Open source thrives on community participation.
If your question isn't answered here:
- Check the comprehensive README.md
- Review BUILD.md for technical details
- Look at TESTING.md for feature information
- Create an issue on GitHub
Remember: Your eyes deserve regular breaks. Use EyeBreak and stay healthy! 👁️✨