👁️ EyeBreak

Your Eyes Deserve a Break

A simple, minimalistic, distraction-free macOS app that helps reduce digital eye strain by following the scientifically-backed 20-20-20 rule.

Features • Installation • Quick Start • Contributing • License

Digital eye strain affects millions of people who spend hours in front of screens. The 20-20-20 rule is a simple, scientifically-backed method to reduce eye fatigue:

Every 20 minutes of screen time
Look at something 20 feet away (about 6 meters)
For 20 seconds

This gives your eye muscles a chance to relax and reduces the risk of eye strain, headaches, dry eyes, and neck pain.

• 🎯 Menu Bar Integration - Lightweight app that lives in your menu bar, never intrusive
• ⏰ Smart Timer System - Customizable work/break intervals with intelligent pausing
• 🌫️ Screen Blur During Breaks - Gentle enforcement to help you actually take breaks
• 🔔 Pre-Break Notifications - 30-second warning before breaks start
• 😴 Automatic Idle Detection - Pauses when you're away from your Mac
• 🎨 Beautiful UI - Clean, modern SwiftUI interface

• 🍅 Pomodoro Mode - Built-in 25/5 work/break cycles
• 🎵 Sound Effects - Optional audio cues for breaks
• 🎭 Multiple Break Styles - Blur screen, notification only, or guided eye exercises
• ⚙️ Flexible Settings - Adjust intervals from 10-60 minutes
• 🎨 Theme Customization (v2.0) - Personalize colors with Default, Random, or Custom themes
• 🎯 Custom Icons (v2.0) - Choose from 16 professional SF Symbols for reminders
• ⏰ Smart Schedule (v2.1) - Set work hours and active days for intelligent reminder management
• 🚀 Auto-Start Timer (v2.1) - Automatically begin timer when app launches
• 💧 Water Reminders (v2.1) - Smart hydration reminders with blur screen or ambient pop-up styles
• 🚀 Launch at Login (v2.1) - Automatic startup when you log into your Mac
• 🔒 Screen Lock Pause (v2.2) - All timers automatically pause when Mac screen locks
• ⏱️ Unified Dashboard (v2.2) - See all timer countdowns in real-time at a glance

• 📊 Daily Statistics - Track your break history with beautiful charts
• 🏆 Streak Tracking - See how many consecutive days you've maintained healthy habits
• 💡 Smart Insights - Get personalized recommendations based on your usage

• 🔒 Privacy-First - Zero data collection, everything stays on your Mac
• ♿️ Accessibility Support - Full VoiceOver, Dynamic Type, and Reduced Motion support
• 🌐 No Internet Required - Works completely offline

• Live Countdown - See remaining time directly in the menu bar
• Dynamic State Icons - Eye icons change based on timer state (active, paused, break)
• Monospaced Digits - Clean, stable display that doesn't shift
• Smart Tooltips - Hover for detailed status information

• Improved Header - Gradient icon badge with shadow effects
• Better Close Button - Enhanced visibility with visible border
• Polished Skip Button - Stronger border and shadow for clarity
• Visual Separation - Increased divider visibility

• Gradient Styling - Linear and angular gradients across all views
• Spring Animations - Smooth, natural-feeling transitions
• Hover Effects - Unified hover behavior on interactive elements
• Rounded Design - Friendly, modern typography

• Hidden Scrollbar - Cleaner About section appearance
• Compact Layout - Optimized spacing throughout
• Consistent Headers - New SectionHeaderView component
• Enhanced Stat Boxes - Gradient backgrounds for visual interest

• ⌘⇧S - Start timer
• ⌘⇧X - Stop timer
• ⌘⇧B - Take break now (with Smart Schedule override)
• ⌘⇧R - Show ambient reminder (with Smart Schedule override)
• ⌘⇧W - Show water reminder (with Smart Schedule override)

See Full v2.3.0 Release Notes | v2.2.0 Release Notes | Water Reminder Guide

• Default Theme - Classic vibrant style
• Random Color - 20 curated palettes, fresh colors each session
• Custom Theme - Full control over all colors and effects
• Professional Icons - SF Symbol picker replaces emoji input

See v2.0.0 Release Notes

• macOS: 14.0 (Sonoma) or later
• Xcode: 15.0 or later (for building from source)
• Swift: 5.9+

1. Download EyeBreak-v2.3.0.dmg
2. Remove quarantine (required for unsigned apps):

   cd ~/Downloads
   xattr -cr EyeBreak-v2.3.0.dmg

3. Open the DMG file
4. Drag EyeBreak.app to your Applications folder
5. Launch:

   open /Applications/EyeBreak.app

6. Look for the eye icon 👁️ in your menu bar!

⚠️ Why the terminal command? The app isn't signed with an Apple Developer certificate ($99/year).
macOS blocks unsigned downloads, so you must remove the quarantine flag first.

curl -L https://github.com/cheat2001/eyebreak/releases/download/v2.3.0/EyeBreak-v2.3.0.dmg -o ~/Downloads/EyeBreak.dmg && xattr -cr ~/Downloads/EyeBreak.dmg && open ~/Downloads/EyeBreak.dmg

Then just drag to Applications!

git clone https://github.com/cheat2001/eyebreak.git
cd eyebreak
open EyeBreak.xcodeproj
# Press ⌘R to build and run

See docs/DEVELOPMENT.md for detailed build instructions.

1. Launch EyeBreak - you'll see an eye icon 👁️ in your menu bar
2. Complete the onboarding to learn about the 20-20-20 rule
3. Grant required permissions when prompted
4. Click "Start Timer" to begin your first session

Click the eye icon to access:

• Start/Stop - Begin or pause your break timer
• Take Break Now - Trigger an immediate break
• Settings - Customize your experience
• View Stats - See your break history and progress

• Your screen will blur and show a break overlay
• Follow the on-screen instructions to rest your eyes
• Press ESC or click anywhere to end early (not recommended!)
• The break automatically ends after the configured duration

Access Settings to customize:

EyeBreak requires the following permissions:

1. Go to System Settings > Privacy & Security > Screen Recording
2. Enable the checkbox next to EyeBreak
3. Restart the app

If denied, the app automatically switches to "Notification Only" mode.

• Allow notifications to receive break reminders
• The app will request permission on first launch

Track your progress with comprehensive statistics:

• Daily Breaks: See how many breaks you've completed today
• Break History: 7-day and 30-day charts showing your consistency
• Completion Rate: Percentage of breaks taken vs. skipped
• Streak Counter: Consecutive days of healthy break habits
• Smart Insights: Personalized tips based on your usage patterns

All data is stored locally on your Mac. No cloud sync, no analytics, no tracking.

EyeBreak/
├── EyeBreakApp.swift              # Main app entry point
├── Models/
│   ├── TimerState.swift           # State management
│   └── Settings.swift             # User preferences
├── Managers/
│   ├── BreakTimerManager.swift    # Core timer logic
│   ├── IdleDetector.swift         # Activity monitoring
│   ├── NotificationManager.swift  # Notification handling
│   └── ScreenBlurManager.swift    # Screen blur overlay
├── Views/
│   ├── MenuBarView.swift          # Main menu bar UI
│   ├── SettingsView.swift         # Preferences panel
│   ├── BreakOverlayView.swift     # Break screen overlay
│   ├── OnboardingView.swift       # Welcome flow
│   └── StatsView.swift            # Statistics dashboard
└── Resources/
    └── Assets.xcassets            # App icons and colors

Architecture: Built using MVVM pattern with SwiftUI and Combine. See docs/ARCHITECTURE.md for details.

Run tests before submitting contributions:

# Manual testing checklist
- [ ] Timer starts and counts down
- [ ] Break overlay appears
- [ ] Notifications work
- [ ] Idle detection pauses timer
- [ ] Settings persist across launches
- [ ] Stats update correctly

See docs/TESTING.md for comprehensive testing guide.

Contributions are welcome! We love pull requests from everyone.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read CONTRIBUTING.md for detailed guidelines.

• 🐛 Report bugs
• 💡 Suggest new features
• 📝 Improve documentation
• 🎨 Design UI/UX improvements
• 🌍 Add translations (future)
• ⭐️ Star the project

• Development Guide - Build and run from source
• Architecture - Technical design and structure
• Installation Guide - Detailed installation instructions
• Distribution Guide - Release and distribution process
• Publishing Guide - How to publish releases on GitHub
• Testing Guide - How to test the app
• FAQ - Frequently asked questions

Screen blur not working?

• Grant Screen Recording permission in System Settings
• Restart the app after granting permission

Notifications not appearing?

• Check System Settings > Notifications > EyeBreak
• Enable "Allow Notifications"

Timer not pausing when idle?

• Enable idle detection in Settings
• Adjust the idle threshold if needed

See docs/FAQ.md for more troubleshooting help.

• Smart Schedule with work hours management (v2.1.0)
• Auto-start timer (v2.1.0)
• Launch at login (v2.1.0)
• Water reminder system (v2.1.0)
• Keyboard shortcuts (v2.1.0)
• Custom break messages (v2.0.0)
• Theme customization (v2.0.0)

• Multiple language support
• Break exercise animations with guided movements
• Weekly/monthly detailed reports
• Export statistics to CSV
• Focus mode integration with Do Not Disturb
• Customizable ambient reminder messages

• Team sync (optional, privacy-first)
• Break reminders for calendar meetings
• Integration with calendar apps
• Stretching exercise videos
• Dark mode theme variants

See issues for planned features and vote on what you'd like to see!

This project is licensed under the MIT License - see the LICENSE file for details.

TL;DR: You can use, modify, and distribute this software freely, even commercially. Just include the license notice.

• Inspired by LookAway.app
• Icons by SF Symbols
• Built with ❤️ for healthier screen time habits
• Thanks to all contributors

• 📖 Read the docs
• 💬 Open an issue
• ⭐️ Star the project
• 🐛 Report a bug
• 💡 Request a feature

If EyeBreak helps you maintain healthier screen habits, please consider:

• ⭐️ Starring this repository
• 🐦 Sharing it on social media
• 📝 Writing a blog post about it
• 🤝 Contributing code or documentation