Omarchy Key Light

Omarchy Key Light adds a native Omarchy Quattro bar widget and control panel for Elgato Wi-Fi lights on the local network. It discovers a dynamic number of compatible lights through mDNS and controls one selected light or every available light together.

The plugin does not provision Wi-Fi, update firmware, use cloud services, create accounts, collect telemetry, or expose a network server.

Requirements

• Omarchy Quattro 4.0.1 or a compatible shell plugin API
• Quickshell 0.3.1 or later in the compatible 0.3 series
• Python 3.11 or later
• Avahi with avahi-browse
• One or more compatible Elgato Wi-Fi lights already connected to the same trusted LAN

The implementation uses only the Python standard library and tools already included with the inspected Omarchy installation.

Device compatibility

Compatibility is detected by protocol capability rather than a hard-coded model allowlist. A device must advertise _elg._tcp and successfully provide Elgato's accessory-info and white-light state endpoints. Unsupported Elgato products are skipped without blocking compatible lights.

• Physically validated: Key Light MK.2.
• Expected to support power, brightness, and white color temperature: Key Light, Key Light Air, Key Light Mini, and Ring Light.
• Other current or future Elgato lights work only when they expose the same local Wi-Fi API. Key Light Neo variants that operate only over USB cannot be discovered by this plugin.
• Light Strip models are not a compatibility target. RGB colors, scenes, battery details, firmware updates, and hardware-specific features are not implemented.

Local development

Run validation and tests from the repository root:

scripts/validate
scripts/test

After at least one light is discovered, read-only real-device validation is available with:

scripts/real-device-test

The --apply-visible-changes option identifies and changes the lights briefly, then restores the original settings. Run that option only with the user's explicit approval.

Link the working tree into the user plugin directory, enable the widget in the right bar section, and watch for source changes:

scripts/dev-install
scripts/dev-enable
scripts/dev-watch

The source watcher asks the running shell to rescan after each saved file because recursive file watches do not follow a linked plugin directory. Stop the watcher with Ctrl+C.

Disable or remove the development installation with:

scripts/dev-disable
scripts/dev-remove

The removal command deletes only the verified development link. It keeps custom device names in the user configuration directory.

Installation

For local testing, use the development commands above. After publication, the normal Omarchy installation flow will be:

omarchy plugin add <repository-url>
omarchy plugin enable <plugin-id> --section right

Review third-party plugin source before enabling it. Omarchy shell plugins execute in the user session without a sandbox.

Discovering and naming lights

1. Open the Key Light panel from the lightbulb icon.
2. Select refresh to discover _elg._tcp services and query compatible accessories.
3. Use Identify on a discovered light to make that physical device flash.
4. Double-click its name, or use Rename, to give it a name that matches the user's setup.
5. Press Enter or Save name. Saving an empty name restores the discovered device name.

The plugin uses the accessory serial number as its stable internal identifier. Current hostnames, addresses, and advertised ports are rediscovered, so custom names survive ordinary DHCP changes. Serial numbers are shown in the device list to disambiguate similar lights.

There is no fixed device limit in the plugin data model. Every compatible discovered light appears automatically; the plugin never guesses the user's physical layout.

Usage

The panel defaults to All lights whenever it opens. Select a device from the dynamic list for individual control.

• Power handles on, off, and mixed states. Activating a mixed power control turns available selected lights on.
• Brightness uses the supported 0–100 percent range.
• Color temperature uses 2900–7000 K.
• Moving a slider for All lights sends the same absolute value to every available light.
• The panel shows the global hotkey reminder: Super+Page Up and Super+Page Down raise or lower every available light by five percentage points from anywhere in the session.
• Click the color-temperature value to enter Kelvin directly; enter only the number, without K.
• A failed request to one light does not stop requests to the others.
• Slider traffic is debounced before network requests are sent.

The global shortcuts call the plugin's user-session IPC target. Add these bindings to ~/.config/hypr/bindings.lua if they are not already present:

o.bind("SUPER + PAGE_UP", "Key Lights brighter", "omarchy-shell key-light brightnessUp", { locked = true })
o.bind("SUPER + PAGE_DOWN", "Key Lights dimmer", "omarchy-shell key-light brightnessDown", { locked = true })

The bar tooltip reports single, combined, mixed-power, partial-availability, and unavailable states for any number of lights. The panel supports Tab navigation, Enter or Space activation, and arrow-key slider adjustment.

Troubleshooting

Validate discovery and inspect service logs:

avahi-browse --resolve --terminate --parsable _elg._tcp
scripts/logs

If no lights appear:

• Confirm the lights and computer are on the same LAN or permitted mDNS segment.
• Confirm avahi-browse can resolve _elg._tcp records.
• Check that multicast DNS traffic on UDP port 5353 is allowed.
• Check that local client isolation is disabled for the relevant wireless network.
• Refresh from the panel after a light restarts or changes address.

The plugin uses the port advertised by each mDNS record. It does not require a fixed device address or assume a fixed API port.

Network, privacy, and security

All traffic stays on the local network. The helper accepts commands only through private process standard input and does not listen on a socket. Discovered addresses and hostnames are kept in memory and are not written to the repository or persistent configuration.

Elgato's local light API may be unauthenticated. Use the lights only on a trusted LAN or an appropriately isolated IoT network whose clients are allowed to reach the Omarchy computer only as intended.

The plugin stores only user-defined names keyed by accessory serial number in ~/.config/omarchy-key-light/config.json, with user-only permissions. It does not store Wi-Fi credentials, addresses, or captured device responses. Existing version 1 Left/Right assignments migrate automatically to custom names.

Removal

Disable and remove a published installation through Omarchy:

omarchy plugin disable <plugin-id>
omarchy plugin remove <plugin-id> --yes

Custom device names are intentionally retained. To reset them, remove ~/.config/omarchy-key-light/config.json after the plugin is disabled.

Current limitations

• Initial Wi-Fi setup and firmware updates are not supported.
• Compatibility is capability-based, not model-name-based: a device must advertise _elg._tcp and implement the accessory-info and white-light endpoints used by the plugin. Models not physically tested may still have firmware-specific differences.
• IPv6 discovery is disabled until it can be validated end to end; tested IPv4 records are used.
• Accessory identification depends on firmware support for the local identify endpoint.
• The compatibility target is the installed Omarchy Quattro 4.0.1 shell API and should be revalidated after major shell upgrades.