Display screen brightness level with multi-monitor support and context-aware icons.

 65%    # Medium brightness
 25%    # Low brightness
 95%    # High brightness
 50% | 80%  # Multiple displays

The binary is downloaded automatically from GitHub Releases when you first enable this plugin on macOS. A confirmation dialog will ask if you want to download it.

No manual installation required!

If you prefer to compile manually:

cd ~/.tmux/plugins/tmux-powerkit/src/native/macos
make powerkit-brightness
cp powerkit-brightness ../../bin/

Requirements: Xcode Command Line Tools (xcode-select --install)

If the native helper is not available, the plugin falls back to ioreg (may have stale values on Apple Silicon).

# Debian/Ubuntu
sudo apt install brightnessctl

# Arch
sudo pacman -S brightnessctl

# Fedora
sudo dnf install brightnessctl

# Enable plugin
set -g @powerkit_plugins "brightness"

# Enable plugin
set -g @powerkit_plugins "brightness"

# Display selection
set -g @powerkit_plugin_brightness_display "builtin"  # builtin, external, all, or display ID
set -g @powerkit_plugin_brightness_separator " | "

# Display options
set -g @powerkit_plugin_brightness_show_percentage "true"

# Icons (context-aware based on brightness level)
set -g @powerkit_plugin_brightness_icon ""           # High brightness (>70%)
set -g @powerkit_plugin_brightness_icon_medium ""    # Medium brightness (30-70%)
set -g @powerkit_plugin_brightness_icon_low ""       # Low brightness (<30%)

# Cache duration (seconds)
set -g @powerkit_plugin_brightness_cache_ttl "5"

# Show only on threshold (if brightness is low/high)
set -g @powerkit_plugin_brightness_show_only_on_threshold "false"

The plugin includes a native Objective-C helper (bin/powerkit-brightness) that uses the DisplayServices private framework for reliable brightness reading. The binary is downloaded automatically from GitHub Releases on first use.

Features:

• Accurate real-time values on Apple Silicon
• Lists all connected displays with their type (builtin/external)
• No external dependencies

Output format:

<display_id>:<type>:<brightness>

Example:

1:builtin:69
2:external:-1
3:external:-1

Note: External monitors using DDC/CI return -1 as they don't support the DisplayServices API. For DDC/CI monitors, consider using tools like ddcctl or MonitorControl.

If the native helper is not available, the plugin falls back to ioreg:

• Reads from AppleARMBacklight (Apple Silicon) or IODisplayParameters (Intel)
• May report stale/cached values on Apple Silicon
• Works with internal displays only

Multiple detection methods (in order of preference):

1. sysfs (/sys/class/backlight) - Most reliable, no tools needed
2. brightnessctl - User-friendly CLI tool
3. light - Alternative CLI tool
4. xbacklight - X11-based (legacy)

The powerkit-brightness is a native macOS utility written in Objective-C that provides reliable brightness reading using the DisplayServices private framework. This is the recommended method for Apple Silicon Macs where ioreg may return stale/cached values.

The binary is downloaded automatically from GitHub Releases when you first enable this plugin on macOS. A confirmation dialog will ask if you want to download it.

The source code is located at src/native/macos/powerkit-brightness.m:

#import <Foundation/Foundation.h>
#import <IOKit/graphics/IOGraphicsLib.h>
#import <ApplicationServices/ApplicationServices.h>

// DisplayServices private framework declaration
extern int DisplayServicesGetBrightness(CGDirectDisplayID display, float *brightness);

int main(int argc, const char * argv[]) {
    @autoreleasepool {
        CGDirectDisplayID displays[16];
        uint32_t displayCount = 0;
        
        CGError err = CGGetActiveDisplayList(16, displays, &displayCount);
        if (err != kCGErrorSuccess || displayCount == 0) {
            return 1;
        }
        
        for (uint32_t i = 0; i < displayCount; i++) {
            CGDirectDisplayID displayID = displays[i];
            float brightness = -1;
            int gotBrightness = 0;
            
            BOOL isBuiltin = CGDisplayIsBuiltin(displayID);
            const char *type = isBuiltin ? "builtin" : "external";
            
            int dsResult = DisplayServicesGetBrightness(displayID, &brightness);
            if (dsResult == 0 && brightness >= 0) {
                gotBrightness = 1;
            }
            
            if (gotBrightness) {
                int percentage = (int)(brightness * 100 + 0.5);
                printf("%u:%s:%d\n", displayID, type, percentage);
            } else {
                printf("%u:%s:-1\n", displayID, type);
            }
        }
    }
    return 0;
}

Prerequisites:

• Xcode Command Line Tools: xcode-select --install

Using Makefile (recommended):

cd ~/.tmux/plugins/tmux-powerkit/src/native/macos
make powerkit-brightness
cp powerkit-brightness ../../bin/

Manual compilation:

cd ~/.tmux/plugins/tmux-powerkit/src/native/macos
clang -framework Foundation -framework IOKit -framework ApplicationServices \
      -F /System/Library/PrivateFrameworks -framework DisplayServices \
      powerkit-brightness.m -o powerkit-brightness
cp powerkit-brightness ../../bin/

# Run the helper directly
~/.tmux/plugins/tmux-powerkit/bin/powerkit-brightness

# Expected output (example):
# 1:builtin:69
# 2:external:-1
# 3:external:-1

Each line represents a display:

• Field 1: Display ID (CGDirectDisplayID)
• Field 2: Display type (builtin or external)
• Field 3: Brightness percentage (0-100) or -1 if not available

• External monitors: DDC/CI monitors don't support DisplayServices API and will return -1
• Private framework: Uses DisplayServices which is a private Apple framework (may change in future macOS versions)
• macOS only: This helper is specific to macOS

Note: External monitor brightness is only available if the monitor supports software brightness control via DisplayServices API.

set -g @powerkit_plugins "brightness"

set -g @powerkit_plugins "brightness"
set -g @powerkit_plugin_brightness_display "all"
set -g @powerkit_plugin_brightness_separator " · "

set -g @powerkit_plugins "brightness"
set -g @powerkit_plugin_brightness_display "external"

set -g @powerkit_plugins "brightness"
set -g @powerkit_plugin_brightness_icon "☀"
set -g @powerkit_plugin_brightness_icon_medium "⛅"
set -g @powerkit_plugin_brightness_icon_low "🌙"

set -g @powerkit_plugins "brightness"
set -g @powerkit_plugin_brightness_show_percentage "false"

1. Check if the binary exists:

   ls -la ~/.tmux/plugins/tmux-powerkit/bin/powerkit-brightness

2. Compile the native helper if missing:

   cd ~/.tmux/plugins/tmux-powerkit/src/native/macos
   make powerkit-brightness
   cp powerkit-brightness ../../bin/

3. Test the helper directly:

   ~/.tmux/plugins/tmux-powerkit/bin/powerkit-brightness

4. If compilation fails, ensure Xcode Command Line Tools are installed:

   xcode-select --install

5. Check fallback ioreg values:

   ioreg -c AppleARMBacklight -r
   ioreg -r -k IODisplayParameters

1. Check for backlight devices:

   ls /sys/class/backlight/

2. Try brightnessctl:

   brightnessctl get

3. Verify permissions (sysfs usually requires no special permissions):

   cat /sys/class/backlight/*/brightness

• The ioreg fallback may cache values on Apple Silicon
• Use the native helper for real-time accurate readings (downloaded automatically or compile manually):

  cd ~/.tmux/plugins/tmux-powerkit/src/native/macos && make powerkit-brightness
  cp powerkit-brightness ../../bin/

External monitors using DDC/CI don't support the DisplayServices API. The helper will list them with brightness -1.

For DDC/CI monitor brightness control, consider:

• ddcctl - Command line tool
• MonitorControl - Menu bar app

• The native helper lists all displays with their type (builtin or external)
• Only displays with software brightness control will show values
• Use display="all" to show all available brightness values
• Linux shows first active backlight device only (sysfs limitation)

• PluginVolume - System volume control
• PluginBattery - Battery level monitoring
• PluginCamera - Camera usage indicator
• PluginMicrophone - Microphone mute status