KeyboardBacklightToggle

A small macOS menu bar app that lets you manually turn the keyboard backlight on/off and remembers the last brightness level — unlike some existing tools (e.g. Keylit), which can't restore the previous brightness after turning it off.

No ambient-light automation, no inactivity timer — just manual switching, exactly the way you want it.

Why this app exists

macOS System Settings only offers: a brightness slider, "Adjust keyboard brightness in low light" (ambient-sensor automation), and "Turn keyboard backlight off after inactivity" (a timer). There's no simple on/off toggle that remembers the last value. This app fills that gap.

How it works (technical background)

macOS controls the keyboard backlight internally through an undocumented class called KeyboardBrightnessClient, part of the private /System/Library/PrivateFrameworks/CoreBrightness.framework. This is the same framework System Settings and the brightness keys use.

Because this is a private (undocumented) API, the app binds to it at runtime via the Objective-C runtime (class_getInstanceMethod + method_getImplementation) instead of linking against it statically. Key details discovered at runtime (via method_getTypeEncoding) that aren't documented anywhere else:

• setBrightness:forKeyboard: returns BOOL, brightness is a float, and the keyboard ID is an unsigned long long (UInt64), not an Int — calling it with 0 as the ID "succeeds" silently but does nothing, because it's an invalid device ID.
• The real ID is obtained via copyKeyboardBacklightIDs, and isKeyboardBuiltIn: is used to pick the built-in keyboard when there's more than one.

⚠️ Important notes

• Uses a private/undocumented API. Apple can rename or change it in any future macOS release. If the app stops working after a system update, that's not necessarily a bug in the app.
• Cannot be distributed on the Mac App Store — Apple rejects private API usage during review.
• The app is not signed or notarized. On first launch of a downloaded .app, macOS Gatekeeper will likely warn you about an unidentified developer. Fix: System Settings → Privacy & Security → scroll down to the blocked-app notice → "Open Anyway". Alternatively, build the app yourself from source (see below) — this sidesteps the Gatekeeper issue entirely, since a locally built app has no quarantine flag.
• Tested on macOS 26 (Tahoe), Apple Silicon (M1). Device IDs and method signatures may differ on other macOS versions or architectures.

Building from source

Requires Xcode Command Line Tools (xcode-select --install).

git clone <this-repo-url>
cd KeyboardBacklightToggle
./build_app.sh
mv KeyboardBacklightToggle.app /Applications/

The script compiles the binary (swift build -c release), builds an .icns icon from AppIcon.iconset, and assembles KeyboardBacklightToggle.app.

Usage

The app runs as a menu bar icon (no window, no Dock icon). The menu contains:

• Turn backlight on — restores the last used brightness
• Turn backlight off
• Set to 25/50/75/100%
• Quit

To launch automatically at login: System Settings → General → Login Items → + → select the app in /Applications.

Ideas for further development

Things that could be added, in case anyone's interested:

• A keyboard shortcut for quick on/off toggling
• Detecting and surfacing the "locked by system" state (isBacklightSaturatedOnKeyboard:)
• Fade animation on toggle (setBrightness:fadeSpeed:commit:forKeyboard:)

License

Public domain / Unlicense — do whatever you want with it, no attribution needed. See LICENSE.

Acknowledgements

Discovering the KeyboardBrightnessClient class, and confirming that CoreBrightness works on Apple Silicon, builds on the work of the KBPulse and TwinKley projects.