Hue Instant Control

Read-only rule (important):

• For “list/what’s in …” requests, do exactly 1 hueGateway call: inventory.snapshot, then answer from the snapshot.
• Avoid chaining resolve.by_name for simple listing; you can match names directly in result.rooms[] / result.zones[] and filter result.lights[].

Only use Bash/curl when:

• the user explicitly asks for bash/curl,
• tool calling is unavailable, or
• Hue Gateway tooling is disabled by config / access policy.

Performance goal (always)

• Goal: operate the Hue Gateway with near-zero errors and minimal latency.
• Default: 1 tool call per user request (prefer hueGateway; otherwise 1 Bash tool call bundling all curl calls).
• Do not waste time: avoid repeated health/discovery work once the gateway is known reachable.
• Always use tight timeouts on curl so fallbacks are instant.

Safety + UX rules (always)

1. Never guess the target.
   • If the room/zone/light is unclear or ambiguous, ask a quick follow-up.
2. Avoid “whole house” surprises.
   • If the request affects more than 2 rooms, or uses words like “all”, “everywhere”, “house”, “downstairs”, ask for confirmation.
3. Do what the user meant, not what they said literally.
   • Example: “make it cozy” → turn on + dim + warm color temp.
4. Be honest about execution.
   • Only claim lights changed if you actually executed the API call (via Bash), or the user confirms they ran your curl.
5. Prefer room-level control (grouped_light) unless the user asks for a specific individual light.

Rooms vs zones (do not confuse these)

Hue has rooms and zones:

• A room contains lights.
• A zone groups multiple rooms (often “Downstairs/Upstairs/Beneden/Boven”), and zone lighting affects all its rooms.

Users often say “room” or “in <name>” when they really mean an area that could be either a room or a zone. Treat room/zone naming as interchangeable user language.

When the user gives a name (e.g. “Keuken”):

1. Call inventory.snapshot (one tool call).
2. Normalize-match the name against both result.rooms[].name and result.zones[].name.
3. If it matches exactly one → proceed using the correct concept:
   • room match → filter lights by light.roomRid == room.rid
   • zone match → collect zone.roomRids[], then filter lights where light.roomRid is in that set
4. If it matches both a room and a zone → ask which they meant.
5. If it matches neither → ask a quick follow-up and show a few candidates from rooms + zones.

Gateway connection (defaults)

• Base URL (default): http://hue-gateway:8000 (recommended when using docker sandboxd + shared network)
• Auth header (either works for /v2/*):
  • Authorization: Bearer dev-token
  • X-API-Key: dev-key

Environment override knobs:

• BASE_URL: Hue Gateway base URL.
• HUE_AUTH_HEADER: full header line to use for auth (e.g. Authorization: Bearer ... or X-API-Key: ...).
• HUE_TOKEN: bearer token value (used if HUE_AUTH_HEADER is unset).
• HUE_API_KEY: API key value (used if HUE_AUTH_HEADER is unset).

Important: if you execute via a sandboxed Bash tool, localhost refers to the sandbox, not the host machine running Hue Gateway. Important: Bash tool calls do not preserve shell state between tool invocations; keep base URL selection + actions in the same Bash call, or set BASE_URL explicitly each time.

Base URL selection (do this first)

If BASE_URL is not provided, try these in order until health succeeds:

1. http://hue-gateway:8000 (recommended when Hue Gateway is attached to the sandbox network)
2. http://host.docker.internal:8000 (common for Docker Desktop on macOS/Windows)
3. http://localhost:8000 (only works when executing on the same host/network namespace as the gateway)

Common mistakes (avoid)

• Do not use localhost:8000 from a sandboxed Bash tool unless you know the gateway is in the same network namespace.
• Do not parse result.data for clipv2.request; Hue resources are at result.body.data.
• Do not use curl -f for /v2/actions calls (it hides useful JSON error bodies); use curl -sS.
• Prefer RID-based grouped_light.set (names are often missing/ambiguous for grouped lights).
• Do not try to parse curl JSON with python3 - <<'PY' ... json.load(sys.stdin) ... PY (stdin is already used for the Python program). Use python3 -c ... <<<"$JSON" (or jq) instead.

Quick start (recommended path)

1. Select BASE_URL + ensure ready (fast; put this at the top of the same Bash tool call where you run actions):

set -euo pipefail

CURL_HEALTH='curl -fsS --connect-timeout 1 --max-time 2'

BASE_URL="${BASE_URL:-}" # optional: user/environment provided
if [ -z "$BASE_URL" ]; then
  for base in "http://hue-gateway:8000" "http://host.docker.internal:8000" "http://localhost:8000"; do
    if $CURL_HEALTH "$base/healthz" >/dev/null; then
      BASE_URL="$base"
      break
    fi
  done
fi

[ -n "$BASE_URL" ] || { echo "Hue Gateway not reachable from this environment. Set BASE_URL to a reachable base URL."; exit 1; }
BASE_URL="${BASE_URL%/}"
echo "Using BASE_URL=$BASE_URL"

READY_JSON="$($CURL_HEALTH "$BASE_URL/readyz")"
case "$READY_JSON" in
  *'"ready":true'*|*'"ready": true'*) : ;;
  *) echo "Hue Gateway is not ready (ready=false)."; exit 1 ;;
esac

AUTH_HEADER="${HUE_AUTH_HEADER:-}"
if [ -z "$AUTH_HEADER" ]; then
  if [ -n "${HUE_API_KEY:-}" ]; then
    AUTH_HEADER="X-API-Key: $HUE_API_KEY"
  else
    AUTH_HEADER="Authorization: Bearer ${HUE_TOKEN:-dev-token}"
  fi
fi

2. Discover inventory (normalized read model; preferred over raw CLIP resources):

curl -sS --connect-timeout 1 --max-time 8 -X POST "$BASE_URL/v2/actions" \
  -H 'Content-Type: application/json' \
  -H "X-Request-Id: demo-rooms-1" \
  -H "$AUTH_HEADER" \
  -d '{"requestId":"demo-rooms-1","action":"inventory.snapshot","args":{}}'

Optional helper: if this skill is installed under ./.skills (RemcoChat default), you can get a parsed list as:

bash ./.skills/hue-instant-control/scripts/list_rooms.sh

This prints: <room-name>\t<grouped_light_rid>\t<room_rid>.

3. Set a named room (fast + verified) using a single v2 action:

bash ./.skills/hue-instant-control/scripts/room_set_by_name.sh --room "Woonkamer" --brightness 35 --color-temp-k 2400

4. (Optional) Set a room by grouped-light RID using grouped_light.set (RID-based; no guessing):

curl -sS --connect-timeout 1 --max-time 8 -X POST "$BASE_URL/v2/actions" \
  -H 'Content-Type: application/json' \
  -H "X-Request-Id: demo-gl-1" \
  -H "$AUTH_HEADER" \
  -d '{"requestId":"demo-gl-1","action":"grouped_light.set","args":{"rid":"<GROUPED_LIGHT_RID>","state":{"on":true,"brightness":35,"colorTempK":2400}}}'

Note: for clipv2.request responses, Hue resources are at result.body.data (not result.data).

5. Set a named lamp / plug using light.set (fast; no discovery needed):

curl -sS --connect-timeout 1 --max-time 8 -X POST "$BASE_URL/v2/actions" \
  -H 'Content-Type: application/json' \
  -H "X-Request-Id: demo-light-1" \
  -H "$AUTH_HEADER" \
  -d '{"requestId":"demo-light-1","action":"light.set","args":{"name":"Vibiemme","state":{"on":true}}}'

Optional helper script (handles base URL selection + readiness + auth):

bash ./.skills/hue-instant-control/scripts/light_set_by_name.sh --name "Vibiemme" --on true

6. Apply a deterministic “vibe” preset (reduces LLM variability):

bash ./.skills/hue-instant-control/scripts/room_vibe.sh --room "Woonkamer" --vibe cozy

7. Set a named zone (safe by default; requires --confirm when it affects >2 rooms):

bash ./.skills/hue-instant-control/scripts/zone_set_by_name.sh --zone "Downstairs" --on false
bash ./.skills/hue-instant-control/scripts/zone_set_by_name.sh --zone "Downstairs" --on false --confirm

8. List all lights in a named zone (read-only; first-time-right):

bash ./.skills/hue-instant-control/scripts/zone_list_lights.sh --zone "Beneden" --print-ok

9. List lights in a named room (read-only; first-time-right):

bash ./.skills/hue-instant-control/scripts/room_list_lamps.sh --room "Woonkamer" --print-ok

When you need details

• Full reference (discovery flows, parsing patterns, vibe presets, verification, failure handling): references/REFERENCE.md

Resources (Level 3)

• Health + readiness: scripts/health_check.sh
• Room discovery: scripts/list_rooms.sh
• Named lamp/plug control: scripts/light_set_by_name.sh
• Named room control: scripts/room_set_by_name.sh
• Vibe presets (room): scripts/room_vibe.sh
• Named zone control: scripts/zone_set_by_name.sh
• List zone lights (read-only): scripts/zone_list_lights.sh
• List room lamps (read-only): scripts/room_list_lamps.sh