Native macOS app for reading and adjusting display brightness. It opens a regular window and also provides a menu bar brightness control.
swift run BrightnessControlApp./build_app.sh
open ".build/release/Brightness Control.app"The build script embeds Resources/AppIcon.icns into the generated app bundle
and applies an ad-hoc signature. To build a universal app for both Apple Silicon
and Intel Macs:
./build_app.sh --arch arm64 --arch x86_64
open ".build/apple/Products/Release/Brightness Control.app"Multi-architecture --arch builds require full Xcode selected with
xcode-select. On a Command Line Tools-only machine, omit --arch for a local
current-architecture build or use the GitHub Actions universal artifact.
APP_VERSION and APP_BUILD_NUMBER can be set to override the values embedded
in Info.plist.
The Build macOS App GitHub Actions workflow runs the core tests and creates a
universal, ad-hoc-signed app archive on every push to main, pull request, and
manual run. Download Brightness-Control-macOS-universal from the workflow run's
Artifacts section.
Pushing a version tag also creates or updates a GitHub Release and attaches the app archive and its SHA-256 checksum:
git tag v1.0.0
git push origin v1.0.0The automated build is not notarized with an Apple Developer ID. After downloading it, macOS may require the first launch through Control-click > Open.
- Internal display brightness uses Apple's
DisplayServicesAPI for writes. - Internal display status reads
corebrightnessdiag status-info. - External display detection uses
system_profiler SPDisplaysDataType -json. - Virtual displays identified by the
unkn/virtvendor/product pair are excluded from hardware controls and DDC indices. Privacy actions are unavailable when no physical or previously known external display is available. - Packaged Apple Silicon builds use the bundled
BrightnessControlDDCtool (a pinned, hardened m1ddc source build) for external brightness and power. This avoids the older Homebrew tool's crashes when display metadata disappears after power-off. SeeVendor/m1ddc/README.mdfor provenance and local changes. - Power-off sends DPMS once; a crashed write is not replayed. Apple Silicon does not attempt the incompatible legacy IOFramebuffer fallback. Other builds keep the existing system m1ddc/ddcctl and legacy DDC behavior.
- A powered-off monitor may stop accepting DDC entirely; wake it with its power button when necessary. The app does not guarantee automatic external wake.
- Privacy Mode also offers a one-shot action that powers off the external display once without entering the maintained Privacy Mode state, so manually waking the display does not trigger another power-off. With no external display connected, the one-shot action dims the internal display once instead.
- Privacy Mode can stay enabled with only the internal display connected. In that case it keeps the internal display dimmed and does not start lid-sleep protection because no external display is being powered off.
- Lid Sleep Protection registers a protected
SMAppServicelaunch daemon and requires approval in System Settings before external power-off. The daemon holds macOSSleepDisabledonly while an authenticated app session needs it, continuously verifies the state, survives daemon restarts, and restores normal lid sleep after release, app exit, or connection loss. Launch daemons require a signed, notarized application bundle for distribution.
For a local package, build_app.sh uses ad-hoc signing by default; the
installer pins that exact local build's designated requirement and places
the daemon executable in /Library/PrivilegedHelperTools. A normal
SMAppService install fails closed without either that pinned requirement or a
Team ID. Set BRIGHTNESS_CODE_SIGN_IDENTITY to a Developer ID Application
identity and notarize the bundle before distribution.
Install a local build with:
./scripts/install_local_root.sh ".build/release/Brightness Control.app"The script verifies and stages the app in /private/tmp before requesting
administrator authentication, so macOS Documents privacy does not block the
privileged installer. Use --preflight to validate the same staging path
without installing.
- Display state refreshes automatically on launch, app activation, screen changes, wake/session events, and a short background interval. The app does not expose a manual refresh button.
The installed Command Line Tools environment does not include XCTest or Swift
Testing, so this package uses a small executable test runner:
swift run BrightnessControlCoreTestRunner
./scripts/test_ddc.shObserved in this repository on macOS 26.5.1 on 2026-10-08:
- A sandboxed
system_profiler SPDisplaysDataType -jsonreturned the GPU but omitted its connected displays, whilepgrepcould not access the process list. The same queries with host authorization found the physical monitor and running app. An empty sandbox result is not evidence that no screen is attached; use an authorized host query to establish the hardware and running binary. - Swift compilation first failed to write its Clang module cache, then printed
an SDK/compiler incompatibility diagnostic. A host-authorized build using the
same toolchain passed that stage. Check the first cache/permission error before
replacing the SDK;
--disable-sandboxdoes not remove the parent agent sandbox. - The local installer retains app backups with the same bundle identifier.
Native UI selection by bundle identifier was ambiguous; selecting the full
installed
.apppath resolved it. Compare installed/build executable hashes and the UI's backend name to distinguish the running app from a local build.
These observations apply to the agent sandbox and local installer layout, not all macOS shells. Recheck after changes to the sandbox, toolchain, OS or installer. Hardware-free DDC regressions and successful reads while a monitor is on do not verify physical power-off or wake. Record manual wake separately from a successful software wake; the 2026-10-08 repair was installed and read-verified without a second physical power-off test.