Calendar Reminder - macOS Menu Bar App

A native macOS menu bar application that displays unmissable meeting reminders with support for EventKit (macOS Calendar), Google Calendar, and Microsoft Outlook.

Features

• Menu Bar Integration: Lives in your menu bar, always accessible
• Floating Reminders: Unmissable overlay windows that appear even in fullscreen apps
• Multiple Calendar Sources: EventKit (macOS Calendar), Google Calendar, Outlook
• Smart Meeting Links: Automatically detects and extracts Zoom, Google Meet, Teams, Webex links
• Battery Efficient: Uses NSBackgroundActivityScheduler for minimal battery impact
• Customizable Timing: Configure when reminders appear before meetings
• Snooze & Dismiss: Full control over your reminders

Requirements

• macOS 14.0 or later
• Xcode 15.0 or later
• Swift 5.9 or later

Project Structure

CalendarReminder/
├── App/                    # App entry point and lifecycle
│   ├── CalendarReminderApp.swift
│   ├── AppDelegate.swift
│   └── Info.plist
├── Core/                   # Business logic
│   ├── Models/            # Data models
│   ├── Services/          # Calendar, OAuth, Notifications
│   └── Storage/           # SwiftData, Keychain
├── UI/                    # User interface
│   ├── MenuBar/          # Status bar controller
│   ├── Reminder/         # Reminder window
│   └── Settings/         # Settings views
└── Resources/            # Assets and sounds

Building the Project

Using Swift Package Manager (SPM)

# Install dependencies
swift package resolve

# Build
swift build

# Run
swift run

Using Xcode

1. Open the project in Xcode:

   open CalendarReminder.xcodeproj

2. Build and run (⌘R)

Creating an Xcode Project

Since this uses SPM, you can create an Xcode project:

swift package generate-xcodeproj

Or use Xcode's native SPM support by opening Package.swift directly.

Configuration

Calendar Permissions

On first launch, the app will request calendar access. You can also manually grant access:

1. Open System Settings
2. Go to Privacy & Security → Calendars
3. Enable access for Calendar Reminder

Settings

Access settings via the menu bar icon:

• General: Sound notifications, launch at login
• Calendars: Connect calendar sources (EventKit, Google, Outlook)
• Timing: Configure reminder timing (1-15 minutes before meetings)

Implementation Status

✅ Completed (Phase 1-4)

• EventKit integration with macOS Calendar
• SwiftData models and storage
• Floating reminder windows (NSPanel)
• ReminderScheduler with battery-efficient monitoring
• Meeting link parser (Zoom, Meet, Teams, Webex)
• Dismiss, Snooze, Join Meeting actions
• Settings UI
• Menu bar integration
• Keychain for secure token storage

🚧 In Progress (Phase 5-7)

• Google Calendar OAuth and API integration
• Microsoft Outlook OAuth and API integration
• Calendar source management UI
• Comprehensive testing
• Performance optimization

Architecture Highlights

Battery Efficiency

• Uses NSBackgroundActivityScheduler with 5-minute intervals
• Local caching to minimize API calls
• Only refetches on calendar changes

Floating Windows

• Uses NSPanel with .floating window level
• Configured for fullscreen compatibility (.fullScreenAuxiliary)
• Visible on all desktops (.canJoinAllSpaces)

Cross-Platform Design

• Business logic separated from platform code
• Protocol-based architecture for calendar sources
• Future Windows support planned

Development

Key Files

1. CalendarCoordinator.swift: Orchestrates all calendar sources
2. ReminderScheduler.swift: Core scheduling logic
3. ReminderWindow.swift: Floating window implementation
4. EventKitManager.swift: macOS Calendar integration
5. CalendarReminderApp.swift: App entry point

Adding a New Calendar Source

1. Implement OAuthProvider protocol in Core/Services/OAuth/
2. Create manager in Core/Services/Calendar/ (e.g., NewCalendarManager.swift)
3. Add conversion to CalendarEvent model
4. Update CalendarCoordinator to include new source
5. Add UI in CalendarSourcesView.swift

Testing

Manual Testing

• Create test calendar events in macOS Calendar
• Verify reminders appear at configured time
• Test dismiss, snooze, join meeting actions
• Verify fullscreen compatibility
• Check battery usage in Activity Monitor

Unit Tests (TODO)

swift test

Future Enhancements

• Windows support using WinUI
• Custom snooze durations
• Multiple reminder times per event
• Calendar filtering by calendar name
• All-day event handling
• Recurring event optimization
• Quick meeting notes
• Meeting statistics and analytics

Contributing

This is a personal project, but suggestions and feedback are welcome!

License

Copyright © 2026. All rights reserved.

Troubleshooting

Calendar Access Issues

• Check System Settings → Privacy & Security → Calendars
• Restart the app after granting permissions

Reminders Not Appearing

• Verify calendar events exist in the next 24 hours
• Check reminder timing settings
• Ensure app is running (menu bar icon visible)

High Battery Usage

• Check Activity Monitor for CPU usage
• Disable unused calendar sources
• Report if consistently >5% battery impact

Support

For issues or questions, please check:

1. System Settings → Privacy & Security → Calendars
2. Console.app for error logs (search "CalendarReminder")
3. Activity Monitor for performance issues