# Lumen: auto brightness for macOS that reads your screen

> Lumen is a GPL-3.0 macOS menu bar app that adjusts display brightness from what is actually on screen, learning your preferences from the brightness keys you already press. It is for laptop users who work at night, not for external monitor setups.

**anishathalye/lumen** — Magic auto brightness based on screen contents 💡

- Repository: https://github.com/anishathalye/lumen
- Website: https://anishathalye.com/lumen/
- Stars: 2,426 · Forks: 57
- Language: Objective-C
- License: GPL-3.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/anishathalye-lumen

## The problem Lumen solves on a MacBook at night

Manual brightness is a compromise. Set the screen for a bright web page and the terminal becomes unreadable; set it for the terminal and every browser tab glows. macOS auto brightness reads ambient light, not pixels, so it cannot tell the difference between a full-screen editor and a photo gallery in the same room. Lumen takes the other input: the screen contents themselves. The README describes the behaviour plainly, brightening when you are looking at a dark window such as a full-screen terminal and darkening when you are looking at a bright window such as a web browser. The target user is someone on a laptop, working in mixed light, who moves between dark and light windows often enough that the brightness keys have become a reflex. It is a menu bar application, so there is no window to manage and no separate settings app to open.

## How Lumen decides what brightness to set

Two mechanisms do the work. The first is screen capture: the README states that Lumen grabs the screen to see whether dark or light content is being displayed, which is why macOS asks for screen recording permission on first run. The second is learning from your own input. The README's central claim is that you control Lumen simply by using your brightness keys, and that it will automatically learn your preferences. In practice that means the app is not applying a fixed curve from average pixel luminance to a brightness value. It observes where you land after you correct it, and adjusts future decisions toward that. This is the part worth understanding before adopting it: the first day or two will feel wrong in places, because the model has not seen your corrections yet. The repository layout confirms the shape of the project: an Xcode project directory, a Lumen source directory, and an assets folder holding the demo GIF. There is no daemon, no config file, and no command line interface documented in the README.

## Installing Lumen with Homebrew and granting screen recording permission

The README calls Homebrew the easiest way to install, through a project-specific tap rather than the default cask list. Run the following in a terminal.

```bash
brew install --cask anishathalye/tap/lumen
```

The cask pulls the app from the tap and places it in your applications folder. On first launch macOS will ask for screen recording permission, which the README explains is needed because Lumen grabs the screen to judge whether the content is dark or light. If you dismiss the prompt, the README gives the manual path: System Preferences > Privacy & Security > Screen & System Audio Recording, then check the box next to Lumen. The README also notes that releases are not signed with a developer key, so the first launch of an unsigned application requires the standard macOS workaround. If you would rather not use Homebrew, the README points to pre-built binaries on the releases page. After installation, open a full-screen terminal and a bright web page in turn and watch the brightness move; correct it with the brightness keys and let the learning settle over a few sessions.

## Where Lumen is the wrong tool

The README is unusually direct about incompatibilities, and they are not edge cases. Lumen is not supposed to work with auto brightness enabled, so the "Automatically adjust brightness" feature in System Preferences has to be turned off first. It is also not compatible with f.lux or Night Shift, and the README says it may not work properly while you are using those. That rules out a common workflow: many people run f.lux precisely because they want warmer colours at night, and Lumen and f.lux are competing for the same display state. The second limitation is hardware. Lumen does not currently include native support for external monitors. The README suggests a workaround through Lunar to sync an external monitor's brightness with the laptop screen, but that is a second application, not a Lumen feature. If your setup is a docked MacBook with two displays, Lumen is controlling one of them at best. Finally, screen recording permission is a broad grant. Lumen needs the pixels, and macOS does not offer a narrower permission for this, so anyone unwilling to give an application that level of access should not install it.

## Alternatives to Lumen and how they differ

The README lists several reimplementations of the same idea on other platforms, and the author states plainly that he has not personally audited their code. The differences are mostly language and platform rather than approach. bencevans/lumenaire and epilande/lux are cross-platform implementations written in Node.js. meh/dux and maximbaz/wluma are Linux implementations written in Rust and C respectively, and the README notes that both add some extra features beyond Lumen's behaviour. autolume/autolux is a Linux implementation in Python, and AlaaAlShammaa/Luminance is a Windows implementation in Java. For a macOS user comparing against something already installed, the relevant contrast is with f.lux and Night Shift rather than with these ports: those tools shift colour temperature on a schedule or by ambient light, while Lumen changes backlight brightness in response to on-screen content. They are not substitutes, and the README treats them as conflicting rather than complementary. If you are on Linux, one of the ports is the realistic option, since Lumen itself is a macOS menu bar application.

## Maintenance, licensing and what an upgrade costs you

The repository is not archived and the last push was on 2026-06-28, the same day as the v1.3.1 release. That release followed v1.3.0 on 2025-06-17, and before that v1.2.2 on 2020-12-26, so the release history is uneven: a long gap, then two releases roughly a year apart. Reading anything into that cadence would be guesswork. What matters for an adopter is that there is no configuration file to migrate and no documented upgrade procedure, because the README does not document one. Upgrading means replacing the application bundle, which for Homebrew users is the usual cask upgrade path. The cost of an upgrade is therefore low, but so is the visibility: the README does not document rollback, so if a new release misbehaves there is no stated way to return to the previous version other than reinstalling it manually from the releases page. On licensing, Lumen is released under GPLv3, copyright Anish Athalye, with the full text in LICENSE.txt. The practical implication of a copyleft licence is that redistributing a modified build carries source obligations. That is a statement about the licence, not legal advice; check with someone qualified if you plan to ship a modified version.

## Conclusion

Adopt Lumen if you work on a MacBook at night and want brightness to follow what is on screen without touching the keys. Skip it if you drive external monitors, rely on Night Shift or f.lux, or want to keep auto brightness on, because the README states Lumen is not supposed to work in those setups. Before installing, confirm you are willing to grant screen recording permission to an unsigned binary distributed through a Homebrew tap, and check that the release you pull matches the version you expect.

## FAQ

### What exactly is Lumen?

It is a menu bar application for macOS that sets screen brightness based on your screen contents, brightening for dark windows and darkening for bright ones. It learns your preferences from your own use of the brightness keys.

### How do I install Lumen?

The README recommends Homebrew via the project tap, with the command brew install --cask anishathalye/tap/lumen. Pre-built binaries are also available from the releases page, and the README notes releases are not signed with a developer key.

### How do I set up Lumen after installing it?

You need to grant screen recording permission, either when it is first requested or through System Preferences > Privacy & Security > Screen & System Audio Recording. The README also says to disable the "Automatically adjust brightness" feature in System Preferences.

### How do I use Lumen?

You use it by continuing to press your brightness keys. The README states that you control Lumen simply by using your brightness keys and that it learns your preferences automatically.

### What is Lumen?

Lumen is a menu bar application for macOS that magically sets the screen brightness based on your screen contents, as the README puts it. It is released under GPLv3.

## Sources

- [anishathalye/lumen on GitHub](https://github.com/anishathalye/lumen)
- [License: GPL-3.0](https://github.com/anishathalye/lumen/blob/master/LICENSE)
- [Project website](https://anishathalye.com/lumen/)
- [README](https://github.com/anishathalye/lumen/blob/master/README.md)
- [Releases](https://github.com/anishathalye/lumen/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/anishathalye-lumen