EyeGuard

Protect your eyes — backed by medical guidelines, not vibes.

EyeGuard is a macOS menu-bar companion that translates published ophthalmology and occupational-health research into a smart break schedule. Every interval, every notification tier, and every exercise routine in this app is anchored to a citable source — the AAO 20-20-20 rule (Jeffrey Anshel), OSHA Computer Workstation Guidelines, the EU Screen Equipment Directive 90/270/EEC, and NIOSH eye-strain prevention guidance.

Why this matters: looking at a screen for hours collapses the ciliary-muscle accommodation reflex (causing Computer Vision Syndrome), freezes posture (driving RSI), and impairs systemic circulation. No single break type fixes all three. EyeGuard layers micro / macro / mandatory breaks so your eyes, your musculoskeletal system, and your circulation each get the rest the literature says they need.

Install: brew tap MashellHan/tap && brew install --cask eye-guard

Screenshots

菜单栏弹窗 — Menu Bar Popover

The control center: live eye-health score, next-break countdown, today's stats, mode picker (Apu mascot ↔ Notch island), one-click break / exercise / tip.

阿普精灵 — Apu Mascot

A draggable always-on-top creature that reacts to your break cadence, tracks your cursor, and floats contextual health tips.

强制休息 — Mandatory Break Overlay

Tier-3 full-screen overlay (used for the 2-hour mandatory break per EU 90/270/EEC). Countdown ring, current health score, dismiss policy enforced by the chosen reminder mode.

数据面板 — Dashboard

Today's health score, breaks taken vs. skipped, screen time, longest continuous session, and a per-component score breakdown so you can see exactly which dimension is dragging your score down.

Display Modes

EyeGuard ships with two mutually-exclusive display surfaces. Pick the one that matches your workflow — switch anytime from the menu-bar picker, and your choice persists across launches.

阿普精灵 (Apu mascot, default)

The mint-green creature that lives in the corner of your screen, reacts to your break cadence, and floats a speech bubble with health tips. Best when you want a warm, always-visible companion.

灵动岛 (Dynamic Notch)

Inspired by MioIsland, the Notch mode reuses the MacBook's camera-housing area as a glanceable status surface.

• Collapsed: a color-coded status dot (green → yellow → red as continuous-use time crosses 10 / 15 / 20 min) next to the MM:SS timer.
• Expanded (hover or click): today's health score, next-break countdown, Break Now button.
• Pop banner: pre-break alerts slide out of the notch as a typewriter banner instead of a separate overlay.
• Preferences: horizontal offset (±30pt), hover-activation speed, opt-in software notch on external monitors.

All underlying business logic — BreakScheduler, ActivityMonitor, exercise sessions, tips, dashboard, health score — is shared between both modes. Notch is a pure view layer, not a rewrite.

Medical Basis (the part that actually matters)

EyeGuard uses three break types targeting three different physiological systems. Even if you rest your eyes every 20 minutes, the 120-minute mandatory break is still necessary — each break addresses a problem the others can't fix.

Break Type	Interval	Duration	Physiological Target	Source
Micro Break	20 min	20 sec	Ciliary-muscle accommodation spasm (near-focus fatigue)	AAO 20-20-20 Rule (Jeffrey Anshel)
Macro Break	60 min	5 min	Musculoskeletal strain, RSI, postural fatigue	OSHA Computer Workstation Guidelines
Mandatory Break	120 min	15 min	DVT risk, systemic circulation, cognitive reset	EU Directive 90/270/EEC, NIOSH

• Micro breaks relax the ciliary muscles. Looking 20 ft away lets the lens flatten, reducing accommodation strain — the core mechanism behind digital eye strain (Computer Vision Syndrome).
• Macro breaks address the rest of your body. After an hour your neck, shoulders, and back need movement; static posture leads to repetitive strain injuries that 20 seconds of distance gazing cannot fix.
• Mandatory breaks protect against prolonged-sitting risks. After 2+ hours of continuous use, blood pooling in the legs increases DVT risk and cognitive performance degrades. A 15-minute break allows systemic-circulation recovery and mental reset.

Engineering rule: any change to break intervals, durations, or escalation timing must cite a source (AAO / OSHA / EU 90/270/EEC / NIOSH). No vibes-based medical constants. See CLAUDE.md.

References

• American Academy of Ophthalmology (AAO): 20-20-20 Rule
• OSHA: Computer Workstation Guidelines (regular hourly breaks)
• EU Screen Equipment Directive 90/270/EEC (mandatory breaks every 2 hours)
• WHO: Regular breaks and ergonomic positioning
• NIOSH: Eye strain prevention guidelines
• Cornell University Ergonomics: Computer Vision Syndrome research

Features

Core Protection

• 20-20-20 Rule: Micro-breaks every 20 minutes (look 20 ft away for 20 seconds)
• Hourly Macro-Breaks: 5-minute breaks every hour (OSHA)
• Mandatory Breaks: 15-minute breaks every 2 hours (EU 90/270/EEC)
• 3-Tier Notification Escalation: System notification → floating overlay → full-screen overlay
• Idle Detection: Auto-pauses timers when you step away
• Smart Snooze: 5-minute snooze with auto-resume

Health Monitoring

• Real-time Health Score (0-100): break compliance, continuous-use discipline, screen time, break quality
• Score Trend Tracking: improving / stable / declining
• Daily Markdown Reports: hourly breakdown, compliance stats, recommendations
• Data Persistence: JSON daily data with restart continuity

Dashboard & Analytics

• Today / History / Breakdown tabs
• SwiftUI Charts: daily screen-time bars + health-score trend lines
• 7 / 30 day history from daily JSON files
• Pie chart for score-component breakdown

Eye Exercises (眼保健操)

• 5 guided routines: focus shifting, figure-8, circle rotation, distance gazing, palming
• Animated step-by-step instructions
• Optional audio guidance
• Progress tracking with mascot celebration

Medical Tips

• 25 evidence-based tips sourced from AAO, WHO, NIOSH, and peer-reviewed research
• Bilingual (Chinese / English)
• Tip rotation every 30 minutes via mascot speech bubble

Late Night Guardian (v1.4)

• Auto-activates after 22:00, gentle sleep reminders, warm amber tints, night-specific usage tracking

Color Balance (v1.5)

• Periodic dominant-color sampling, complementary-color suggestions to reduce strain, hourly color-family trends

Sound Effects (v1.6)

• Break notification sounds, ambient nature audio (ocean, rain, forest, wind), celebration chimes, volume control

AI Insights (v1.8)

• Rule-based insight engine (no external API required), daily-report insights, periodic mascot insights, menu-bar contextual summary, hourly-pattern analysis

Reminder Modes (v2.4)

• Gentle / Aggressive (default) / Strict / Custom presets
• Per-break-type dismiss policy (skippable / postpone-only / mandatory)
• Break absorption when multiple breaks align
• Postpone system: up to 2× delay on postpone-only breaks

Setting	Gentle	Aggressive (default)	Strict
Micro notification	System banner	Floating popup	Full screen
Micro dismiss	Skippable	Skippable	Mandatory
Macro notification	Floating popup	Floating popup	Full screen
Macro dismiss	Skippable	Skippable	Postpone only (2×)
Mandatory notification	Full screen	Full screen	Full screen
Mandatory dismiss	Skippable	Postpone only (2×)	Mandatory
Escalation	Tiered (2m → 5m)	Direct	Direct

Internationalization (v3.3)

• Full localization via String Catalog (Localizable.xcstrings)
• Default UI language: 简体中文; English available
• In-app language picker (Follow System / 中文 / English)

Install

Homebrew (recommended)

brew tap MashellHan/tap
brew install --cask eye-guard

From source

git clone https://github.com/MashellHan/eye-guard.git
cd eye-guard
bash scripts/build-app.sh
open EyeGuard.app

Build

swift build                              # compile
swift test                               # run unit tests
bash scripts/build-app.sh                # produce EyeGuard.app
open EyeGuard.app                        # launch

Requirements

• macOS 14.0 (Sonoma) or later
• Accessibility permission (for activity monitoring)
• Notification permission (for break reminders)

Architecture

EyeGuard/Sources/
├── AI/                 # LLM service protocol + insight generator
├── Analysis/           # Color analysis engine
├── App/                # App entry, menu bar, preferences
├── Audio/              # Sound effects + ambient audio
├── Dashboard/          # Analytics dashboard with Charts
├── Exercises/          # Guided eye-exercise routines
├── Mascot/             # Floating mascot character (Apu)
├── Models/             # Core data models
├── Monitoring/         # Activity monitor (keyboard / mouse)
├── Notch/              # Dynamic notch (灵动岛) view layer
├── Notifications/      # 3-tier notification system
├── Persistence/        # JSON data persistence
├── Protocols/          # Dependency-injection protocols
├── Reporting/          # Daily report generation + health score
├── Scheduling/         # Break scheduler engine
├── Tips/               # Medical tip database
└── Utils/              # Constants, logging, formatting

Tech Stack

• Swift 6.0 with strict concurrency
• SwiftUI + AppKit (menu bar, floating windows, notch overlay)
• SwiftUI Charts (dashboard visualization)
• Swift Testing framework
• os.Logger for structured logging
• Protocol-oriented architecture with dependency injection

License

MIT