Omahub
← All plugins
S

Omarchy Hue Light Control and Theme Sync

by sethchev

Control Philips Hue lights from the bar connected to Hue Bridge. Syncs with your active Omarchy theme!

GitHub

Security review

No obvious issues detected

Deterministic scan — not a security guarantee

None
Risk level
None
Analyzed commit
813ad65
Scanned
4 days 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
813ad65
Reviewed
4 days ago

The plugin is a transparent Philips Hue control widget: it reads local credentials, talks to the Hue bridge over HTTPS with a bundled CA, and writes only user-level config/state files. The theme-sync hook and pairing/cleanup scripts are user-initiated and match the documented behavior. No obfuscation, credential exfiltration, destructive commands, or hidden persistence were 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/sethchev/omarchy-philips-hue --enable
Desktop #quickshell

omarchy-philips-hue

Omarchy / Quickshell bar widget for controlling Philips Hue lights over the bridge's local HTTPS APIs (v1 and v2).

<p align="center"> <img src="preview.png" alt="omarchy-philips-hue panel screenshot" width="360"> </p>

Features

  • Bar icon (lightbulb) that opens a control panel
  • Toggle all rooms, individual rooms, or single lights
  • Per-room Scenes dropdown with Relax, Read, Natural Light, and Tv Mode presets; existing bridge scenes are reused and missing presets are created automatically
  • Every room and light row is tinted with the bulb's current color (hue/sat, color temperature, or XY as reported by the bridge)
  • Per-room brightness slider for dimming or brightening every light in a room together
  • Per-light brightness slider
  • Per-light color temperature slider (warm ⇄ cool white)
  • Per-light color wheel picker (hue + saturation) and color temperature slider; both hidden for lights in rooms with theme sync enabled
  • Favorite rooms stay pinned at the top of the panel; use the star beside a room (favorites are stored in hue-theme.json)
  • Preview the active theme on an opted-in room immediately from its expanded controls
  • Bridge failures and unreachable lights are shown in the panel, with the last successful refresh time and a manual retry; polling backs off while the bridge is unreachable and pauses while the panel is closed
  • State refreshes are serialized and validate command output before updating the panel, preventing overlapping requests or partial results from appearing as a successful refresh
  • Keyboard-accessible room, favorite, and scene controls
  • Supports both the classic Hue API v1 and CLIP API v2
  • Reads credentials from ~/.local/state/omarchy/settings/hue.json
  • Retries / re-fetches state automatically after every change

Requirements

  • Arch Linux + Omarchy (Quickshell-based shell)
  • python3 (for the pairing script), omarchy-shell

Install

omarchy plugin add https://github.com/sethchev/omarchy-philips-hue.git --enable

Pairing with the bridge

On first run the bar shows a lightbulb icon. Click it to open the panel, then click Pair with bridge. This opens a terminal — press the link button on your Hue bridge when prompted. The script discovers the bridge, requests an application key, checks whether v2 is available, and writes ~/.local/state/omarchy/settings/hue.json. New pairings use v2 when the bridge supports it and otherwise use v1. The panel picks up the new credentials automatically within seconds.

You can also pair manually:

~/.config/omarchy/plugins/omarchy-philips-hue/pair.sh

Pass an IP directly to skip auto-discovery: pair.sh 192.168.1.14. Set PHILIPS_HUE_API_VERSION=v1 or v2 to force a version during pairing; the default is automatic detection.

Moving an existing pairing to v2

The v1 username is also the v2 application key, so you do not need to re-pair or press the bridge button. Verify the existing key and switch the plugin atomically with:

python3 ~/.config/omarchy/plugins/omarchy-philips-hue/hue-api.py migrate-api v2

Existing credential files without an apiVersion remain on v1 until this is run. To switch back, use the same command with v1. Re-pairing is only needed if the key was revoked or the bridge was reset or replaced.

Scenes

Open a room in the panel, expand its Scenes menu, and choose one of four built-in presets for that room:

  • Relax — warm, comfortable, lower-brightness white
  • Read — brighter warm white for reading
  • Natural Light — bright neutral/cool daylight
  • Tv Mode — dim accent lighting for color-capable bulbs, with warm fallback for white-only bulbs

When you choose a scene, the plugin first looks for a same-named Hue scene for that room/zone and recalls it only there. If the bridge does not already have that preset for a room, the plugin creates a room-scoped scene from the built-in recipe and then recalls it. This keeps existing Hue app scenes intact while filling in missing presets such as Natural Light.

Syncing lights with the omarchy theme

Requires thpm (Theme Hook Plugin Manager, io.github.oldjobobo.thpm). Theme sync drives off the theme-set hook chain, which thpm manages and which sources its environment from ~/.local/share/thpm/lib/theme-env.sh. Without thpm installed, the 45-hue.sh hook does not run and lights stay on their last color. Install the thpm plugin before enabling theme sync.

A theme-set hook (45-hue.sh, vendored in theme-sync/) recolors every room/zone from the active theme whenever you run omarchy theme set: either the accent color, or — when scenes are enabled — a per-light scene built from the theme's palette. The bar widget picks the change up within its 15 s poll.

Per-room opt-out

Each room that is switched on gets a Theme Sync toggle in the panel, right below its own toggle. Every room starts out synced; toggling a room off excludes it from theme changes until you re-enable it.

Turning a room's Theme Sync back on immediately force-syncs that room to the current theme's color right away (no need to switch themes again). This is handy for catching a room up after it was excluded during a theme change.

Rooms with at least two color-capable lights also get a Scene Mode toggle next to it. With Scene Mode on, the room's lights are colored from the theme's palette instead of one uniform accent (see Theme scenes).

While a room is synced, its lights' color wheel and color temperature slider are hidden in the panel — the hook owns their color, so manual picking would be overwritten anyway. Rooms with sync off keep full manual control.

The toggle states live under the themeSync key of hue-theme.json (missing room = enabled), and are picked up by the hook immediately — no restart needed.

Install

The repo ships everything needed under theme-sync/:

~/.config/omarchy/plugins/omarchy-philips-hue/theme-sync/enable-theme-sync.sh

This copies 45-hue.sh to ~/.config/omarchy/hooks/theme-set.d/ (making it executable) and writes a default hue-theme.json to ~/.config/omarchy/settings/ if you don't have one yet. Existing settings are preserved. Re-run the theme-sync installer after upgrading from a pre-v2 plugin so the installed hook uses the shared v1/v2 client. No shell restart is needed — the hook is picked up on the next omarchy theme set.

To install manually instead:

mkdir -p ~/.config/omarchy/settings
omarchy hook install theme-set theme-sync/45-hue.sh
cp -n theme-sync/hue-theme.json ~/.config/omarchy/settings/hue-theme.json
chmod 600 ~/.config/omarchy/settings/hue-theme.json

Behavior is configured in ~/.config/omarchy/settings/hue-theme.json:

{
  "enabled": true,
  "transition": 20,
  "groups": ["all"],
  "bri": null,
  "turnOn": false,
  "themes": {},
  "scene": false,
  "sceneRooms": {},
  "themeSync": {}
}
  • transition — fade length in tenths of a second (20 = 2 s)
  • groups — ["all"], or a subset of room/zone names to sync
  • bri — optional forced brightness (1–254); leave null to keep each light's current brightness
  • turnOn — true to turn lights on when syncing; false leaves on/off state untouched
  • themes — per-theme hex overrides, e.g. { "spacehaven": "#0c8184" }; themes without an override use their own accent
  • scene — true to enable theme scenes globally; off by default (false). Rooms missing from sceneRooms follow this value
  • sceneRooms — per-room scene override map written by the panel's Scene Mode toggles, e.g. { "office": true }
  • themeSync — per-room opt-out map written by the panel's Theme Sync toggles, e.g. { "kitchen": false }; rooms missing from the map are synced

Theme scenes

When a synced room has two or more color-capable lights and Scene Mode is on for it, the hook stops painting the whole room one color and instead maps the theme's palette onto the room's lights, one hue per light. Only rooms with at least two color-capable lights are eligible — single-light and white-only rooms always fall back to the uniform accent, as do rooms with Scene Mode off.

The scene palette is built from colors.toml:

  1. accent first (a themes override re-colors just this anchor)
  2. the named palette colors in file order (red, yellow, green, cyan, blue, magenta, then bright_*)
  3. any other plain #rrggbb keys in file order

Keys that describe surfaces rather than lights (backgrounds, foregrounds, selection, muted, borders, tabs) are skipped, and duplicate hexes are collapsed. Colors are assigned in room light order; light #1 always gets the accent. If a room has more lights than the palette, the palette cycles.

transition, bri, and turnOn behave the same as in uniform mode, applied per light, so scenes fade in together. The bridge applies the writes immediately; the panel's rows and the room swatch pick the scene up within the normal 15 s poll.

Test the hook without changing your theme:

bash ~/.config/omarchy/hooks/theme-set.d/45-hue.sh <theme-slug>

Remove

~/.config/omarchy/plugins/omarchy-philips-hue/cleanup.sh
omarchy plugin remove omarchy-philips-hue

The cleanup script removes your bridge credentials from ~/.local/state/omarchy/settings/hue.json. Run it before removing the plugin so no auth token is left behind.

Notes

  • Speaks to the bridge over HTTPS on your LAN — no cloud and no SDK. v1 uses /api/<username>/...; v2 uses /clip/v2/resource/... with the existing username in the hue-application-key header.
  • TLS is verified with the bundled hue_bridge_cacert.pem, the official Philips Hue root CA from Signify. During pairing, the bridge's unique ID is read from /api/config and saved as bridgeId in hue.json; requests are then addressed to that ID so the bridge certificate's hostname is matched, while the connection itself goes straight to the bridge's IP.
  • Automatic discovery tries mDNS first (avahi-browse -t -r _hue._tcp, the same on-LAN mechanism the official Hue app uses), then falls back to Philips' hosted lookup discovery.meethue.com. Pass an IP directly to pair.sh to skip auto-discovery entirely.
  • If bridgeId is missing (e.g. from an older config), the panel warns "TLS verification disabled" — re-run pair.sh to restore full certificate verification.
  • Existing installations default to the classic v1 local API for backward compatibility. New pairings prefer CLIP v2. Room and light id_v1 values are retained as logical IDs when using v2, so room-specific theme settings survive migration.
  • Credentials are stored per-user in ~/.local/state/omarchy/settings/hue.json; keep that file out of version control.