A native macOS application that automates your keyboard backlight based on time triggers, sunrise/sunset, and custom schedules. Built with SwiftUI and IOKit, this menu bar app runs quietly in the background and intelligently manages your MacBook's keyboard illumination. I built this side project for learning purposes and to solve a personal annoyance – manually adjusting keyboard backlight throughout the day.
- Swift & SwiftUI
- IOKit Framework
- macOS AppKit
- Combine Framework
- Core Location (for sunrise/sunset)
Here's what you can do with MacLightController:
Menu Bar Integration: Lives discreetly in your menu bar, accessible with a single click. No dock icon, no window clutter – just a simple status item that's always available when you need it.
Keyboard Backlight Control: Manually adjust brightness with a smooth slider or let automations handle it. Instant feedback shows the current brightness level as you adjust it.
Flexible Automation Triggers: Create schedules based on specific times, sunrise/sunset, or recurring intervals. Mix and match triggers to build the perfect lighting schedule for your workflow.
Sunrise & Sunset Awareness: Automatically adjusts based on actual sunrise and sunset times for your location. Optionally add offsets (e.g., "30 minutes before sunset") for even more control.
Smart Scheduling: Set different brightness levels for different times of day. Bright backlight during the day, dimmed for evening work, off at night – all handled automatically.
Location Services: Uses Core Location to determine accurate sunrise/sunset times. You can allow automatic location detection or manually set your coordinates for privacy.
Background Operation: Runs efficiently without draining battery or consuming significant resources. The app is optimized for Apple Silicon and uses minimal memory.
- Click Menu Bar Icon: Open quick controls
- Option+Click: Open full settings
- Quick Slider: Adjust brightness instantly from menu
I started this project out of personal frustration. I'd manually adjust my keyboard backlight multiple times a day – bright in the morning, dimmed in the afternoon, off at night. It felt like something a computer should handle automatically.
My first challenge was figuring out how to actually control the keyboard backlight programmatically. macOS doesn't expose this through standard APIs, so I had to dive into IOKit, Apple's low-level framework for hardware communication. Reading through obscure documentation and forum posts, I eventually found the IOKit services that manage keyboard illumination.
Building the automation engine was the next step. I needed a scheduler that could handle different types of triggers – specific times, sunrise/sunset calculations, and repeating intervals. I designed a plugin-based architecture where each trigger type is a separate module, making the system extensible for future automation types.
Integrating Core Location for sunrise/sunset was interesting. I had to handle user privacy concerns (some people don't want apps knowing their location), permission requests, and fallbacks for when location isn't available. I added manual coordinate entry as an alternative.
The UI evolved significantly. Initially, I built a full windowed app, but that felt heavyweight for something so simple. I pivoted to a menu bar-only interface, which felt much more macOS-native. Users can quickly adjust brightness or check automations without opening a separate window.
Apple Silicon optimization was important. I made sure the app ran natively on M-series chips, took advantage of power efficiency features, and minimized background activity. The goal was an app you could leave running 24/7 without noticing any performance impact.
Testing edge cases took time. What happens if the system wakes from sleep mid-automation? What if the user manually changes brightness – should automations override that? These scenarios required careful thought about user expectations and system behavior.
During this project, I've picked up important skills and a deeper understanding of macOS development, system-level programming, and native app design.
SwiftUI for macOS: Building menu bar apps taught me about NSStatusItem, popover presentations, and macOS-specific UI patterns. SwiftUI on macOS differs from iOS in subtle but important ways.
IOKit Framework: Diving into hardware control through IOKit was eye-opening. I learned about service matching, property iteration, and how to safely communicate with hardware drivers without causing system instability.
App Sandbox Limitations: I discovered why App Sandbox had to be disabled for this app – direct hardware access isn't allowed in sandboxed environments. This taught me about macOS security models and trade-offs.
Time-Based Triggers: Implementing a reliable scheduler taught me about timezone handling, daylight saving time transitions, and how to calculate future execution times accurately.
Astronomical Calculations: Working with sunrise/sunset taught me about solar position algorithms, coordinate systems, and how to account for atmospheric refraction in civil twilight calculations.
Event-Driven Architecture: Building a plugin system for different trigger types taught me about abstract interfaces, dependency injection, and how to make code extensible without over-engineering.
Hardware Abstraction: Learning to interact with hardware through abstraction layers taught me about driver architecture, service providers, and how operating systems manage hardware resources.
Background Operations: Keeping an app running efficiently in the background taught me about task scheduling, power management APIs, and how to be a "good citizen" in the macOS ecosystem.
Menu Bar Apps: I learned the conventions for menu bar applications – when to show badges, how to structure menus, and providing quick actions versus full settings.
Native Look & Feel: Matching system aesthetics taught me about design tokens, respecting user preferences (like reduced motion), and creating interfaces that feel like they belong to macOS.
This project taught me that solving your own problems leads to the best learning experiences. Because I used the app daily, I noticed every rough edge and iterated until it felt polished.
Working with low-level APIs like IOKit was intimidating initially, but it demystified system programming. Hardware isn't magic – it's just APIs and protocols, accessible once you understand the patterns.
Most importantly, I learned about restraint in feature design. I resisted adding display brightness, volume control, and other automations. By keeping the scope focused on keyboard backlight, I shipped a polished, reliable tool instead of a half-baked automation suite.
- Add support for display brightness automation
- Implement dark mode toggle automation
- Add system volume control schedules
- Create Focus mode integrations
- Add Shortcuts app integration for macOS
- Implement smooth brightness transitions (fade in/out)
- Add condition-based triggers (e.g., "when plugged in")
- Create preset profiles for different workflows
- Add notification preferences for automation events
- Implement import/export for automation configurations
To run the project in your local environment, follow these steps:
-
Clone the repository:
git clone https://github.com/Shipwithsimo/MacLightController.git cd MacLightController -
Open the project in Xcode 15 or later:
open MacLightController.xcodeproj
-
Select the MacLightController scheme and your Mac as the destination
-
Build and run (⌘R) the project
-
Grant necessary permissions:
- Accessibility: Required for keyboard backlight control
- Location Services (optional): For sunrise/sunset features
System Requirements:
- macOS 13.0 (Ventura) or later
- Apple Silicon (M1/M2/M3/M4) Mac
- MacBook with backlit keyboard
A minimal menu bar icon that shows the current backlight status. Clicking it reveals a clean popup with a brightness slider and a list of active automations. The settings panel lets you create new automations with intuitive date/time pickers and trigger options. The entire interface feels like a native macOS system preference.