---
name: hue
description: "Read and control Philips Hue Bridge lighting installations through local CLIP v2 or the Hue Remote API with SecretRef-backed credentials and guarded lighting changes."
user-invocable: true
requires:
  bins:
    - node
config_variables:
  - id: hue-bridge-host
    env: HUE_BRIDGE_HOST
    required: true
    scope: "Local Hue Bridge HTTPS base URL used in gateway http_request URLs"
    how_to_obtain: "Find the bridge IP through the Hue app, router DHCP table, mDNS, or discovery.meethue.com, then store it in chat with `/env set HUE_BRIDGE_HOST \"https://<bridge-ip>\"`."
credentials:
  - id: hue-application-key
    kind: api_key
    required: true
    secret_ref:
      source: store
      id: HUE_APPLICATION_KEY
    scope: "Philips Hue CLIP v2 hue-application-key header"
    how_to_obtain: "Press the bridge link button, build the link request with `node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab`, and send its `httpRequest` through the gateway. Set the returned `HUE_APPLICATION_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUE_APPLICATION_KEY \"<application-key>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUE_APPLICATION_KEY \"<application-key>\"`."
  - id: hue-remote-refresh-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: HUE_REMOTE_REFRESH_TOKEN
    scope: "Hue Remote API OAuth token used for off-LAN API calls"
    how_to_obtain: "Create a Hue developer app and complete the Hue Remote API OAuth flow. Set `HUE_REMOTE_REFRESH_TOKEN` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HUE_REMOTE_REFRESH_TOKEN \"<token>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HUE_REMOTE_REFRESH_TOKEN \"<token>\"`."
  - id: hue-remote-access-token
    kind: bearer
    required: false
    secret_ref:
      source: store
      id: HUE_REMOTE_ACCESS_TOKEN
    scope: "Hue Remote API short-lived access token used as Authorization bearer"
    how_to_obtain: "Run `node skills/hue/hue.cjs --format json remote oauth-token` after configuring the Remote API client id, client secret, and refresh token; the emitted gateway request captures the access token into `HUE_REMOTE_ACCESS_TOKEN`."
metadata:
  hybridclaw:
    category: home-automation
    short_description: "Philips Hue local CLIP v2 reads plus approval-gated light, group, scene, and automation control."
    tags:
      - hue
      - philips-hue
      - smart-home
      - lighting
      - r21
    related_roadmap:
      - R21.114
      - R48
    issue: 1118
    stakes_tiers:
      green:
        - local-bridge-status
        - local-bridge-list
        - local-device-list
        - local-light-list
        - local-grouped-light-list
        - local-room-list
        - local-zone-list
        - local-scene-list
        - local-motion-list
        - local-temperature-list
        - local-light-level-list
        - local-button-list
        - local-behavior-instance-list
        - local-entertainment-configuration-list
        - local-eventstream
      amber:
        - local-link-button
        - remote-oauth-token
        - remote-bridges
        - remote-light-list
        - local-light-on
        - local-light-off
        - local-light-brightness
        - local-light-color
        - local-group-on
        - local-group-off
        - local-group-brightness
        - local-group-color
        - local-room-on
        - local-room-off
        - local-group-recall-scene
        - local-scene-recall
        - local-behavior-enable
        - local-behavior-disable
        - local-scene-create
        - local-behavior-create
      red:
        - local-bridge-config-timezone
        - local-bridge-config-software-update
    escalation:
      writes: confirm-each
      route: f14
    cost_measurement:
      system: UsageTotals
      sub_limit_key: hue
---

# Philips Hue

Use this skill for Philips Hue Bridge lighting inspection and guarded control.
The primary path is local HTTPS to the Hue Bridge CLIP v2 API. Use the Hue
Remote API only when the operator explicitly needs off-LAN control or local
bridge access is unavailable.

## Safety Rules

1. Use `skills/hue/hue.cjs` for every supported Hue request shape. Do not
   handcraft CLIP v2 URLs or JSON bodies when the helper supports the action.
2. Read current light, room, zone, and scene state before changing lights.
3. Treat local reads as green, local light/group/scene/behavior changes as
   amber, off-LAN Remote API calls as amber, and bridge configuration writes as
   red.
4. For amber/red operations, use the helper to build the request shape, explain
   the target and expected effect, and stop for explicit operator approval
   before sending the emitted `httpRequest` through the gateway.
5. Include the target light, grouped light, room, scene, behavior, bridge id,
   action, and expected physical effect in approval text.
6. Never paste the Hue application key, OAuth client secret, or remote token
   into chat. The helper emits `secretHeaders` or `<secret:...>` placeholders
   for gateway-side resolution.
7. Hue Bridge certificates are self-signed by default. The helper marks local
   bridge HTTPS requests with a scoped `allowSelfSignedTls` flag for the
   gateway `http_request` proxy. Do not use a blanket insecure TLS bypass.
8. If a live call returns `401` or `unauthorized_user`, stop after that first
   failed call and re-link the bridge with the link-button flow.
9. In chat sessions, do not diagnose Hue runtime config by running
   `hybridclaw env list`, `hybridclaw secret list`, or other local CLI commands
   from `bash`; those commands can inspect the wrong runtime or fail because of
   the host Node version. Use gateway `http_request` errors and any `/env show`
   or `/secret list` output the operator provides.
10. If `HUE_BRIDGE_HOST` is configured and `HUE_APPLICATION_KEY` is missing,
   say only that the application key is missing. Do not ask the operator to
   find the bridge IP again. Ask them to press the physical link button, then
   build `node skills/hue/hue.cjs --format json bridge link --app-name
   hybridclaw --instance-name lab`, send the emitted `httpRequest`, and store
   the returned Hue credential secret through the helper-emitted
   `captureResponseFields`.
11. When linking after the operator presses the bridge button, run `bridge
   status` first. If the live status result reports `linkbutton: true`,
   immediately run `bridge link` without `--host`. If it reports
   `linkbutton: false`, tell the operator that the configured bridge did not
   report an active button press and ask them to press and release the physical
   link button once, then retry immediately. If `linkbutton` is absent, do not
   treat that as proof the button is inactive; modern bridge config responses
   can omit the field.
12. When running the link request itself, do not pass `--host` unless the
   operator explicitly provides a new override URL in the same turn. The default
   link request must use `<env:HUE_BRIDGE_HOST>` so the gateway resolves the
   env-store value.
13. If the operator shows `/env show HUE_BRIDGE_HOST`, treat that value as the
   current configured bridge URL. If a failed request used any other host,
   report that the helper was called with the wrong host and retry the same
   operation with no `--host` override.
14. If `HUE_BRIDGE_HOST` is missing, first reuse an exact Hue Bridge URL from
   current context or workspace memory when one is present. Ask the operator to
   find the bridge IP only when no exact URL is available.
15. If a gateway `http_request` error says `Stored secret HUE_APPLICATION_KEY
   is not set`, treat `HUE_BRIDGE_HOST` as already resolved for that request.
   Do not say the bridge host may be missing, do not tell the operator to run
   `hybridclaw env set`, and do not repeat the same read calls. Switch directly
   to the link-button setup path in rule 10.
16. If a private-host or gateway policy denial blocks a local bridge request,
   first inspect the current workspace network policy. Managed read-only LAN
   access already allows GET reads to RFC1918 hosts, and managed read-write LAN
   access allows the supported methods. If either managed LAN mode covers the
   attempted Hue request, report that mismatch as a gateway policy-evaluation
   bug instead of adding another rule. Do not edit policy by hand, do not add
   broad bridge rules, and do not tell the operator a gateway restart is
   required; workspace network policy is read per request.
17. If a local Hue request fails with a certificate verification or
   self-signed TLS error, do not ask for `HUE_BRIDGE_HOST` again, do not suggest
   plain HTTP on port 80, and do not invent a URL auth route or workspace
   policy setting for TLS. Re-run the exact helper-emitted `httpRequest` with
   `allowSelfSignedTls: true`; if that field is absent, rebuild the request with
   `skills/hue/hue.cjs`.

## Command Contract

The helper is deliberately thin: it only turns clean subject/verb arguments
into gateway-ready `httpRequest` payloads. It does not write env values, edit
network policy, call the gateway, poll the bridge, or store secrets.

Show helper usage:

```bash
node skills/hue/hue.cjs --help
```

Build local CLIP v2 read requests, then pass the emitted `httpRequest` object
to the gateway `http_request` tool:

```bash
node skills/hue/hue.cjs --format json bridge list
node skills/hue/hue.cjs --format json device list
node skills/hue/hue.cjs --format json light list
node skills/hue/hue.cjs --format json grouped-light list
node skills/hue/hue.cjs --format json room list
node skills/hue/hue.cjs --format json zone list
node skills/hue/hue.cjs --format json scene list
node skills/hue/hue.cjs --format json motion list
node skills/hue/hue.cjs --format json behavior list
node skills/hue/hue.cjs --format json entertainment list
```

Read a bounded diagnostic eventstream window:

```bash
node skills/hue/hue.cjs --format json eventstream read --duration 30s
```

Prepare guarded write operations:

```bash
node skills/hue/hue.cjs --format json light on --id <id>
node skills/hue/hue.cjs --format json light off --id <id>
node skills/hue/hue.cjs --format json light brightness --id <id> --pct 60
node skills/hue/hue.cjs --format json light color --id <id> --xy 0.4317,0.4147
node skills/hue/hue.cjs --format json light color --id <id> --mirek 366
node skills/hue/hue.cjs --format json grouped-light on --id <grouped_light_id>
node skills/hue/hue.cjs --format json grouped-light brightness --id <grouped_light_id> --pct 60
node skills/hue/hue.cjs --format json scene recall --id <scene_id>
node skills/hue/hue.cjs --format json behavior disable --id <behavior_id>
node skills/hue/hue.cjs --format json bridge timezone --id <bridge_id> --timezone Europe/Berlin
```

The helper marks amber and red operations with `requiredGrant`. Send the
emitted `httpRequest` only after the operator approves the described effect.

Link a bridge after pressing the physical link button:

```bash
node skills/hue/hue.cjs --format json bridge status
node skills/hue/hue.cjs --format json bridge link \
  --app-name hybridclaw \
  --instance-name lab
```

The status command emits a `/api/config` request shape with
`<env:HUE_BRIDGE_HOST>` and no secret header. Use it to confirm the configured
bridge reports `linkbutton: true` before sending the link request. The link
command emits a single `/api` request shape with `<env:HUE_BRIDGE_HOST>` and
only a `devicetype` body. Send that request through the gateway while the
button is active, then store the returned Hue credential secret as
`HUE_APPLICATION_KEY` through the emitted `captureResponseFields`. Do not pass
`--host` for normal chat setup.

Use Remote API reads only when off-LAN access is needed:

```bash
node skills/hue/hue.cjs --format json remote oauth-token
node skills/hue/hue.cjs --format json remote bridge list
node skills/hue/hue.cjs --format json remote light list --bridge <id>
node skills/hue/hue.cjs --format json remote room list --bridge <id>
```

## Setup

Store the local bridge URL in the env store, then press the bridge link button,
build the link request, send the emitted `httpRequest` through the gateway, and
let the gateway capture the returned Hue credential secret as the application
key.

In chat:

```text
/env set HUE_BRIDGE_HOST "https://<bridge-ip>"
node skills/hue/hue.cjs --format json bridge status
node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab
```

From a local terminal:

```bash
hybridclaw env set HUE_BRIDGE_HOST "https://<bridge-ip>"
node skills/hue/hue.cjs --format json bridge status
node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab
```

Managed LAN HTTP access covers local RFC1918 bridge reads according to the
workspace policy setting. The helper does not create or modify that setting.

For the Hue Remote API, create a developer app, complete the OAuth flow, then
set the resulting values in this order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set the
   `HUE_REMOTE_*` secrets.
2. Browser `/chat` or TUI fallback:

```text
/secret set HUE_REMOTE_CLIENT_ID "<oauth-client-id>"
/secret set HUE_REMOTE_CLIENT_SECRET "<oauth-client-secret>"
/secret set HUE_REMOTE_REFRESH_TOKEN "<refresh-token>"
node skills/hue/hue.cjs --format json remote oauth-token
/secret set HUE_REMOTE_BRIDGE_ID "<bridge-id>"
```

3. Local console fallback:

```bash
hybridclaw secret set HUE_REMOTE_CLIENT_ID "<oauth-client-id>"
hybridclaw secret set HUE_REMOTE_CLIENT_SECRET "<oauth-client-secret>"
hybridclaw secret set HUE_REMOTE_REFRESH_TOKEN "<refresh-token>"
node skills/hue/hue.cjs --format json remote oauth-token
hybridclaw secret set HUE_REMOTE_BRIDGE_ID "<bridge-id>"
```

## Resource Coverage

The helper allowlists the initial CLIP v2 resource set from the OpenHue
OpenAPI contract and Philips Hue CLIP v2 docs: `bridge`, `device`, `light`,
`grouped_light`, `room`, `zone`, `scene`, `motion`, `temperature`,
`light_level`, `button`, `behavior_instance`, and
`entertainment_configuration`. Arbitrary `/clip/v2/resource/<type>` passthrough
is rejected.

## Result Handling

- Base answers on successful live Hue API results from the current turn.
- For scene recall, expect `recall: { action: "active" }`.
- For light/group color, use either XY coordinates or mirek color
  temperature, not both.
- Eventstream output can reveal occupancy. Keep diagnostic reads short and do
  not create a long-lived subscription from this skill.
- On gateway policy denial for a local bridge, inspect the current workspace
  network policy first. If managed read-only LAN access covers the GET read, or
  managed read-write LAN access covers the attempted method, report a gateway
  policy-evaluation bug and do not add a duplicate bridge rule. If LAN access
  is off, tell the operator which LAN HTTP access setting is missing. Do not
  tell the operator to restart the gateway.
- If policy denial persists despite a matching managed LAN setting, report the
  helper-emitted host, method, and path. Do not substitute Remote API results
  unless the operator asks for off-LAN fallback.
- On certificate verification or self-signed TLS failures for local Hue HTTPS,
  explain that the request must include the helper's `allowSelfSignedTls: true`
  field and retry once with the helper-emitted request. Do not ask whether the
  bridge supports plain HTTP, do not ask for the bridge host again, and do not
  claim a gateway TLS route or workspace policy is required.
- On missing Hue configuration, report exactly which configured names are
  present and which are missing. If the gateway says `Stored secret
  HUE_APPLICATION_KEY is not set`, do not say `HUE_BRIDGE_HOST` is unknown or
  missing; the `<env:HUE_BRIDGE_HOST>` placeholder already resolved far enough
  to reach secret-header injection. In chat, give only this slash-command
  recovery path:

```text
Press the Hue bridge link button, then let me run:
node skills/hue/hue.cjs --format json bridge status
node skills/hue/hue.cjs --format json bridge link --app-name hybridclaw --instance-name lab

The emitted `captureResponseFields` rule captures the returned Hue credential
secret into `HUE_APPLICATION_KEY`.
```

  Do not include `hybridclaw env set` or ask the operator to set
  `HUE_BRIDGE_HOST` again unless the gateway explicitly reports that
  `HUE_BRIDGE_HOST` itself is missing.
- On a live link response from `/api` with Hue error `type: 101` or description
  `link button not pressed`, run `bridge status` once in the current button
  window. If status reports `linkbutton: true`, retry `bridge link`
  immediately. If status reports `linkbutton: false`, explain that the bridge
  at the configured env-store host is reachable but does not currently report
  an active button press; ask the operator to press and release the physical
  button once, then retry the status and link sequence immediately. If status
  omits `linkbutton`, explain that the bridge status endpoint did not expose
  button state and retry the `/api` link request only when the operator confirms
  the button was just pressed.
- On a live link response saying `generateclientkey is not available` or
  directing the caller to `POST /api/config/connections`, rebuild the request
  with the current helper and retry the emitted `/api` request. The helper must
  not send `generateclientkey`; it should send only `devicetype`.
- On a live link response from `/api/config/connections` with Hue error
  `type: 1`, address `/connections`, or description `unauthorized user`, do not
  claim the button window expired. That endpoint requires an existing
  authorized user on this bridge. Rebuild with the current helper and use the
  unauthenticated `/api` link request without `generateclientkey`.
- If the operator shows `/env show HUE_BRIDGE_HOST` and it differs from the host
  used by a failed request, explain that the request used the wrong override and
  retry with the normal helper command, which emits `<env:HUE_BRIDGE_HOST>`.