Skip to content

About

macOS menu bar app that drives Night Shift from the ambient light sensor

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

LumenShift

A macOS menu bar app that drives Night Shift from the ambient light sensor instead of the clock.

Dark room — Night Shift on Lit room — Night Shift off

Why

macOS only offers Night Shift on a sunset-to-sunrise schedule, which gets it wrong in both directions: a brightly lit office at 9pm gets warmed for no reason, and a dark room at 4pm doesn't. The thing that should drive a warmth filter is how much light is actually falling on the screen — and every Mac with a built-in display already has a sensor measuring exactly that.

LumenShift reads it and switches on the room, not the hour.

How it works

The ambient light sensor has no public API on Apple Silicon. LumenShift resolves IOHIDEventSystemClient symbols at runtime with dlsym and reads the ALS HID event directly. Night Shift is driven through the nightlight CLI, which talks to the same private CoreBrightness framework that System Settings uses.

Naively thresholding a light sensor produces a display that flickers between modes every time someone walks past a lamp. Three mechanisms prevent that:

  • Hysteresis. Separate on and off thresholds. A reading inside the band holds the current state rather than oscillating around a single value.
  • Debounce. A candidate change must persist for a configurable delay before it is applied, so transient light doesn't trigger a switch.
  • Clamshell detection. With the lid shut the internal panel sleeps and its sensor reads near zero regardless of the room, which would pin Night Shift on permanently. CGDisplayIsBuiltin and CGDisplayIsAsleep detect this and take the sensor out of the loop.

An optional gate restricts when the sensor may act at all — a clock window, sunset to sunrise, or a combination. Sun times are computed locally from latitude and longitude using the standard solar position equations, with no network call and no API key.

Polling runs at 5s normally and 1s while the popover is open, so the live readout feels responsive without costing anything when idle.

Requirements

  • macOS 13 or later, and a Mac with a built-in ambient light sensor (2012 and newer, including all Apple Silicon)

  • nightlight: brew install smudge/smudge/nightlight

    Then nightlight schedule off, so macOS doesn't fight the app over the same switch. LumenShift searches /opt/homebrew/bin, /usr/local/bin and ~/bin; a custom path can be set in the UI.

Build

git clone https://github.com/K-M/LumenShift.git
cd LumenShift
./build-app.sh
open dist/

The app is ad-hoc signed but not notarised, so the first launch needs right-click > Open.

Calibration

Open the popover and read the live lux value in your normal evening lighting, then again with the lights off. Set the lower threshold just above the dark reading and the upper one just below the lit reading. Keep a wide gap between them — that gap is the hysteresis band.

Limitations

  • The private API is undocumented and could break in a future macOS release. In practice the interface has been stable since Catalina, but there is no guarantee behind it.
  • Mac App Store distribution is impossible for the same reason.
  • External displays with their own light sensors (Studio Display, LG UltraFine) are not supported; only the built-in sensor is read.

License

MIT

About

macOS menu bar app that drives Night Shift from the ambient light sensor

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages