EyeSee 👁️

A behavior-aware focus timer for macOS that enforces meaningful breaks.

EyeSee is an open-source alternative to traditional break reminder apps. Instead of passively notifying users, it actively adapts to user behavior and introduces controlled friction to encourage real breaks.

---

Features

🕐 Focus Timer

• Configurable focus duration
• Pause, resume, and reset controls
• Menu bar integration for quick visibility

🧠 Behavior Awareness

• Detects mouse and keyboard activity
• Differentiates between active and idle states
• Adjusts break flow based on real usage

🚫 Break Enforcement

• Full-screen break overlay
• Smooth animated transitions
• Short cooldown period to encourage disengagement

🖱️ Cursor-Based Feedback

• Countdown appears near cursor in final seconds
• Lightweight, non-intrusive UX
• Visual feedback without disrupting workflow

⏸️ Snooze Control

• Snooze option becomes available after a delay
• Prevents immediate skipping of breaks
• Encourages intentional user decisions

🖥️ Screen Saver Integration

• Trigger macOS screen saver during breaks
• Helps users fully step away from the screen

---

Architecture

The project follows a modular structure:

EyeSee/
├── Managers/        # App lifecycle and orchestration
├── Services/        # System-level logic (activity, notifications)
├── ViewModels/      # State management
└── Views/           # SwiftUI UI components

---

Getting Started

Requirements

• macOS 13+
• Xcode 15+
• Swift 5+

Installation

Clone the repository and open it in Xcode:

git clone https://github.com/YOUR_USERNAME/EyeSee.git
cd EyeSee
open EyeSee.xcodeproj

Run the app:

Cmd + R

Development

Recommended workflow:

• Cursor / VS Code — editing and refactoring
• Xcode — building and debugging

Build Commands

Command	Action
Cmd + B	Build
Cmd + R	Run
Cmd + Shift + K	Clean

---

Roadmap

• Extract TimerEngine from AppDelegate
• Add break tracking (taken vs. skipped)
• Introduce adaptive break timing
• Improve idle detection accuracy
• Add lightweight local analytics

---

Contributing

Contributions are welcome.

Guidelines:

• Keep changes focused and minimal
• Avoid unnecessary UI complexity
• Prioritize behavior and system logic over visual features
• Ensure code is readable and well-structured

Steps:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Open a pull request

---

License

This project is licensed under the MIT License.

---

Philosophy

Most productivity tools rely on reminders.

EyeSee focuses on behavior.

It introduces friction where needed and adapts to how users actually work.