MKTimer

A simple, elegant menubar timer app for macOS built with Swift and SwiftUI.

Features

• Lives in your menubar - No dock icon, pure menubar app
• Animated hourglass icon - Shows time remaining and empties as countdown progresses
• Quick access countdown timer - Click menubar icon to set timer
• Preset time buttons - 5, 15, 30, 40 minutes
• Custom time input - Enter any duration in minutes
• Pause/resume functionality - Control your timer with ease
• Progress bar - Visual indicator of time remaining
• Desktop notifications - Alert when timer completes
• Keyboard shortcuts - Enter to start, Space to pause/resume, Delete to reset
• Blue gradient app icon - Custom hourglass design

How to Build and Run

Prerequisites

• macOS 13.0 or later
• Xcode 15.0 or later

Building from Xcode

1. Open MKTimer.xcodeproj in Xcode:

   open MKTimer.xcodeproj

2. Select the "MKTimer" scheme at the top

3. Press Cmd + R to build and run

   OR

   Click the Play button (▶) in the top-left corner of Xcode

Building from Command Line

# Build the Release version
xcodebuild -project MKTimer.xcodeproj -scheme MKTimer -configuration Release clean build

# The app will be located at:
# ~/Library/Developer/Xcode/DerivedData/MKTimer-*/Build/Products/Release/MKTimer.app

# Install to Applications folder
cp -r ~/Library/Developer/Xcode/DerivedData/MKTimer-*/Build/Products/Release/MKTimer.app /Applications/

# Launch the app
open /Applications/MKTimer.app

First Launch - Enable Notifications

On first launch, you'll need to grant notification permissions:

1. If LSUIElement is set to false in Info.plist, the app will show a permission dialog - click Allow
2. If set to true (menubar-only mode), go to System Settings → Notifications and enable notifications for MKTimer
3. Once permissions are granted, you can set LSUIElement back to true for menubar-only operation

Running the App

Once running, the app appears in your menubar:

• Idle state: Shows hourglass icon
• Timer running: Shows countdown time (MM:SS) with animated hourglass that empties as time runs out
• Click the icon to:
  • Set a timer (enter minutes or use quick buttons)
  • Start/pause/resume the timer
  • View countdown progress
  • Quit the app

No dock icon will appear - it's a pure menubar app!

Auto-Start at Login

To make MKTimer start automatically when you log in:

1. Open System Settings → General → Login Items
2. Click the + button under "Open at Login"
3. Navigate to Applications and select MKTimer
4. Done! MKTimer will now launch on startup

Project Structure

MKTimer/
├── MKTimer.xcodeproj/          # Xcode project file
├── generate_icon.swift         # Script to generate app icons
├── LICENSE                     # MIT License
├── README.md                   # This file
└── MKTimer/
    ├── MKTimerApp.swift        # App entry point, menubar setup, hourglass animation
    ├── ContentView.swift       # Main UI with timer controls
    ├── TimerManager.swift      # Timer logic and notifications
    ├── Info.plist              # App configuration (LSUIElement = true for menubar-only)
    └── Assets.xcassets/        # App icons and accent color
        ├── AppIcon.appiconset/ # Blue gradient hourglass icons (all sizes)
        └── AccentColor.colorset/ # Orange accent color

Regenerating Icons

If you want to modify the app icon:

# Edit generate_icon.swift to change colors/design
# Then run:
./generate_icon.swift

# Rebuild the app
xcodebuild -project MKTimer.xcodeproj -scheme MKTimer -configuration Release clean build

Usage

1. Start a timer: Click the hourglass icon in your menubar
2. Choose duration: Enter time in minutes or click a preset (5m, 15m, 30m, 40m)
3. Start: Press Enter or click "Start Timer"
4. Watch countdown: The menubar shows time remaining with animated hourglass
   • First quarter: Full hourglass (bottom half filled)
   • Second quarter: Empty hourglass
   • Third quarter: Top half filled
   • Final quarter: Empty hourglass
5. Pause/Resume: Click icon and use Space bar or click button
6. Reset: Click icon and press Delete or click "Reset"
7. Complete: Get a desktop notification when time's up!

Development Notes

Key Technologies

• LSUIElement: Set to true in Info.plist to hide from dock and make it menubar-only
• NSStatusItem: Creates the menubar icon with dynamic title and image
• NSPopover: Shows the timer UI when clicked (.transient behavior for auto-dismiss)
• UserNotifications: Sends desktop notification on completion
• Combine: Reactive updates for menubar display using @Published properties
• Timer: Uses Foundation's Timer for countdown (updates every second)
• SF Symbols: Hourglass icons that change based on progress
  • hourglass.bottomhalf.filled - First quarter
  • hourglass - Second and fourth quarters
  • hourglass.tophalf.filled - Third quarter

Customization Ideas

• Change preset times: Edit the [5, 15, 30, 40] array in ContentView.swift:57
• Modify colors: Change gradient colors in generate_icon.swift or AccentColor
• Different icon animations: Update the progress thresholds in MKTimerApp.swift:63-70
• Add sound alerts: Integrate NSSound in addition to notifications
• Recent timers: Store frequently used durations with UserDefaults
• Different notification sounds: Customize UNMutableNotificationContent.sound

Swift/SwiftUI Concepts Used

• @main and App protocol for app lifecycle
• NSApplicationDelegate with @NSApplicationDelegateAdaptor for AppKit integration
• @ObservedObject and @Published for reactive state management
• ObservableObject protocol for the timer logic
• Combine framework for observing timer state changes
• SwiftUI views and layout with VStack, HStack, Button, TextField
• AppKit's NSStatusBar and NSPopover for menubar functionality
• NSImage.SymbolConfiguration for SF Symbols with custom sizes
• CGContext for precise bitmap image generation

Troubleshooting

Icons are wrong size: Run ./generate_icon.swift to regenerate all icon sizes correctly

Notifications don't work: Check System Settings → Notifications and enable for MKTimer

App doesn't appear in menubar: Check that LSUIElement is set to true in Info.plist

Can't find built app: It's in ~/Library/Developer/Xcode/DerivedData/MKTimer-*/Build/Products/Release/

License

MIT License - see LICENSE file for details.

---

Enjoy your new timer app! 🎉