Omahub
← All plugins
M

Keyboard Backlight

by majesticio

A native Omarchy bar button for cycling and adjusting laptop keyboard brightness

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
335956f
Scanned
1 month ago

No potentially dangerous behavior detected in the analyzed commit.

Automated analysis only — not a security guarantee.

AI advisory review

No obvious issues detected

Language-model assessment · ~deepseek/deepseek-v4-flash-latest — advisory only

None
AI risk level
None
Recommendation
install
Model
~deepseek/deepseek-v4-flash-latest
Analyzed commit
335956f
Reviewed
1 month ago

The plugin is a straightforward bar widget that controls keyboard backlight via brightnessctl, with no network access, install hooks, or privilege escalation. The helper script includes careful state-directory permission checks and atomic writes, and the code is transparent and well-tested. No dangerous or malicious behavior was found.

How this check works

This review combines the deterministic scan (the rule-based results above) with an independent look at the plugin's code by a language model. The model reads a trimmed sample of the repository's files, the manifest, and the README, then gives a plain-language risk level and a recommendation: install (no notable danger), review (look closer first), or avoid (clearly dangerous).

It runs on the same analyzed commit as the deterministic scan and is strictly advisory — it is not a security guarantee and never blocks a plugin by itself. A human moderator still reviews plugins before they are listed.

AI advisory only — automated analysis, not a security guarantee.

Install
$ omarchy plugin add https://github.com/majesticio/omarchy-keyboard-backlight-plugin --enable
Hardware #bar #quickshell #power-management

Keyboard Backlight

Keyboard Backlight is a native Omarchy Quattro bar widget for the laptop keyboard light exposed by Linux as *kbd_backlight*.

The widget stays synchronized with hardware brightness keys, disappears when no compatible device exists, and remembers the last non-zero level so it can restore the light after switching it off.

Keyboard Backlight active in the Omarchy bar

Features

  • One-click cycling through every hardware brightness level and off
  • Scroll-wheel brightness adjustment
  • Hardware-aware brightness steps, including laptops with only two or three levels
  • Periodic state refresh for changes made with keyboard function keys
  • Automatic *kbd_backlight* device detection
  • Optional explicit device selection for systems exposing more than one candidate
  • No daemon, network access, privilege elevation, or configuration outside the plugin's own state file

Requirements

  • Omarchy Quattro with the shell plugin system
  • brightnessctl (included with Omarchy)
  • A keyboard backlight visible under /sys/class/leds/ with kbd_backlight in its name

Check compatibility with:

brightnessctl --list

Installation

Install and enable the published plugin:

omarchy plugin add https://github.com/majesticio/omarchy-keyboard-backlight-plugin.git --enable

The widget is added to the right section by default. Move it with:

omarchy bar move io.github.majesticio.keyboard-backlight --section right

Removal

Disable and remove the plugin with:

omarchy plugin remove io.github.majesticio.keyboard-backlight

The plugin never modifies Omarchy configuration files directly. The command disables the plugin, removes its checkout, and asks Omarchy to rescan plugins. If you also want to erase the remembered non-zero brightness level, remove:

${XDG_STATE_HOME:-~/.local/state}/omarchy-keyboard-backlight/

Controls

Input Action
Left click Cycle through brightness levels and wrap to off
Scroll up/down Increase or decrease brightness
Middle click Toggle off or restore the last non-zero level
Right click Turn the backlight off

The icon uses Omarchy's active color while the backlight is on. Its tooltip shows the exact percentage and updates while it is open when the hardware brightness keys are used.

Configuration

The default device detection is appropriate for most systems. If more than one keyboard-backlight device is present, set the exact brightnessctl device name:

omarchy bar set io.github.majesticio.keyboard-backlight device 'asus::kbd_backlight'

The polling interval defaults to 2000 ms and may be set between 500 and 60000 ms:

omarchy bar set io.github.majesticio.keyboard-backlight refreshInterval 1000

State and security

The helper reads keyboard brightness from /sys/class/leds/ and changes it through brightnessctl. It runs with normal user permissions and never requests elevated privileges.

The most recent non-zero brightness is stored at:

${XDG_STATE_HOME:-~/.local/state}/omarchy-keyboard-backlight/

The directory is restricted to the current user. Brightness actions fail before changing the hardware if no private state root is available or the state path is not safely owned and permissioned. Saved values are read without following symlinks or blocking on special files and are replaced atomically.

No telemetry, network requests, background services, or install hooks are used. The only external runtime dependency is brightnessctl; the widget otherwise uses components supplied by Omarchy Quattro.

Development

Validate the manifest and run the helper tests:

omarchy plugin validate .
python3 -m unittest discover -s tests -v

For local development, clone or symlink this repository to ~/.config/omarchy/plugins/io.github.majesticio.keyboard-backlight, then rescan and enable it through Omarchy's plugin commands.

License

MIT