Key Light for Omarchy

An Omarchy shell (Quickshell) bar widget for the Elgato Key Light and Key Light Air.

Toggle the light from the bar, and open a panel for brightness and colour temperature.

• Bar pill — a lamp icon plus the current brightness (󰛨 55%) when the light is on, dimmed when it is off, and a disconnect icon when it cannot be reached. Hovering shows its state.
• Panel — power switch, brightness slider, and colour temperature in Kelvin (2900K–7000K).

Everything is driven over your local network. No Elgato account, no Control Center, no Stream Deck, nothing leaves your LAN.

Requirements

• Omarchy 4 ("Quattro") or newer, i.e. the Quickshell-based shell — not the older Waybar bar.
• curl and jq (already present on Omarchy).
• avahi-browse, from avahi — used once to find the light. Already present on Omarchy.
• python3, used to read and write the cached address safely.
• An Elgato Key Light or Key Light Air on the same network.

The light needs no setup. It serves a local HTTP API on port 9123 out of the box and advertises itself over mDNS; nothing has to be enabled for it.

Install

omarchy plugin add https://github.com/codemonkey76/omarchy-keylight --enable

Or by hand:

git clone https://github.com/codemonkey76/omarchy-keylight \
  ~/.config/omarchy/plugins/io.github.codemonkey76.keylight

Then add it to a bar section in ~/.config/omarchy/shell.json and run omarchy restart shell.

Configuration

There is nothing you have to configure. The widget finds the light over mDNS, caches its address, and rediscovers automatically if it moves — so a new DHCP lease is not something you have to notice.

One optional setting, on the widget's entry in ~/.config/omarchy/shell.json:

{
  "id": "io.github.codemonkey76.keylight",
  "refreshSeconds": 30
}

refreshSeconds is how often the bar pill re-reads the light while the panel is closed (default 30, minimum 5). While the panel is open it always polls every 5 seconds, so the sliders track changes made from another app.

Usage

Action	Result
Left click	Open / close the panel
Right click	Toggle power
Middle click	Force a refresh
p (panel open)	Toggle power
r (panel open)	Refresh
Esc	Close

It can also be driven over IPC:

omarchy-shell io.github.codemonkey76.keylight toggle   # open/close the panel; also: open, close
omarchy-shell io.github.codemonkey76.keylight power
omarchy-shell io.github.codemonkey76.keylight refresh

Command line

The plugin drives the light through a small script it ships, omarchy-keylight, so discovery, address caching and range clamping have one implementation rather than two that drift. It is useful on its own — put it on your PATH to get keybinds:

ln -s ~/.config/omarchy/plugins/io.github.codemonkey76.keylight/omarchy-keylight \
  ~/.local/bin/omarchy-keylight

omarchy-keylight status              # off  15%  3900K
omarchy-keylight toggle              # also: on, off
omarchy-keylight brightness 40
omarchy-keylight brightness +10      # relative, clamped to 0-100
omarchy-keylight temp 5000           # Kelvin, clamped to 2900-7000

From the command line, raising brightness on a light that is off also turns it on — a keybind gives no visual feedback, so otherwise the key would look broken. The panel deliberately does not do this: its power switch is visible right above the slider, so setting a level for later is a reasonable thing to want there.

Notes on the device

Anything on your network can answer mDNS as a Key Light, so omarchy-keylight treats every answer as untrusted. Responses are capped at 16 KiB (a real light sends about 100 bytes). Discovery accepts only a valid IPv4 address. Every value (on, brightness, colour temperature) is checked against what a Key Light actually reports before anything uses it. Arguments are checked the same way, as plain numbers. The panel also rejects anything from the script longer than one short line.

The cached address (~/.local/state/omarchy-keylight/device) is read and written without following symlinks. Only a small regular file of yours is accepted, and updates replace it atomically.

Two quirks worth knowing if you poke at the API yourself:

• Colour temperature is sent in mireds, not Kelvin — 143 is 7000K, 344 is 2900K, and K = 1000000 / mired. The widget shows Kelvin and converts.
• The light ignores values outside its range instead of clamping them, so an out-of-range write looks exactly like a command that silently did nothing. Both the panel and the script clamp before sending.

Removal

omarchy plugin remove io.github.codemonkey76.keylight

That unregisters the plugin and deletes its directory. If you installed by hand, remove the entry from bar.layout in ~/.config/omarchy/shell.json, delete ~/.config/omarchy/plugins/io.github.codemonkey76.keylight, then run omarchy restart shell.

The plugin stores one thing outside its own directory: the discovered address of the light, cached in ~/.local/state/omarchy-keylight/. Delete it if you want discovery to start over.

Licence

MIT — see LICENSE.