Your home.
In every terminal and agent.

---
name: homekit
description: Control and read the user's real HomeKit and Matter home from the terminal with HomeKit.sh (homekit.sh on a Mac, Linux/WSL/Git Bash via a relay, or HomeKit.ps1 / the HTTP API on Windows), lights (on/off, brightness, any color, white temperature), thermostats, locks, garage doors, blinds, fans, purifiers, humidifiers, TVs, speakers, valves/faucets, robot vacuums and Matter appliances (dishwashers, washers, ovens, EV chargers…), scenes, and cameras (snapshot to clipboard, live window, local stream URL). Use whenever the user mentions a light, room, accessory, scene, camera or "the house", including deferred requests like "make the studio orb green when this is all done" or "flash the office light when the build finishes".
---

# HomeKit via HomeKit.sh

`homekit.sh` talks to the **HomeKit.sh bridge**, a small Mac Catalyst agent that
has HomeKit + Matter access. Every command waits for HomeKit's answer and exits:
`0` ok · `1` failed · `2` ambiguous / not found (candidates printed) · `3` bridge/relay unreachable.

If `homekit.sh` isn't on PATH, it lives at `~/Desktop/HomeKit.sh/homekit.sh`
(`homekit.sh` is the old name and still works).

## Deferred requests ("…when this is all done")

Do the user's actual task first. When it's finished (and verified), run the
home command as your **last step**, then mention it in your final message.
If the work ends in a background process (build, test run, deploy), chain the
command onto that process instead of guessing when it ends:

```sh
xcodebuild … ; homekit.sh set "studio orb" color green
```

To signal the outcome, use two colors: green when it worked, red when it didn't.

```sh
if make test; then homekit.sh set "studio orb" color green; else homekit.sh set "studio orb" color red; fi
```

## Targets

Say accessories the way a person would: `"studio orb"`, `"Orb"`, `"kitchen lights"`,
`"everything in the studio"`, `"all fans"`, a Home-app group name, or an accessory UUID.
Room + name is the safest ("studio orb", not "orb"). Plurals and "all" target groups.

On **exit 2** the bridge prints candidates (`Studio › Orb`, `Kitchen › Orb`…). Pick
one from context and retry with the room in the name. If context doesn't settle it,
ask the user. Never guess between locks, garage doors or security systems.

Discover first when unsure: `homekit.sh find "<words>"` or `homekit.sh ls` (every
accessory, its state, and what it can set).

## Doing things

```sh
homekit.sh set "studio orb" color green           # names, #00ff00, "120,100" (hue,sat)
homekit.sh set "studio orb" color "warm white"    # or kelvin 2700 / kelvin cool
homekit.sh set "desk lamp" brightness 40
homekit.sh set "kitchen lights" color blue brightness 70   # several props at once
homekit.sh on "bedroom tv"  ·  homekit.sh off "studio lights"  ·  homekit.sh toggle fan
homekit.sh set thermostat temperature 70F mode heat        # °F/°C suffix, or the home's units
homekit.sh set "living room blinds" position 30            # also: open / close
homekit.sh set "bedroom tv" input "Apple TV" volume 20
homekit.sh set purifier mode auto speed 60
homekit.sh set dishwasher mode Eco  ·  homekit.sh start dishwasher
homekit.sh start vacuum  ·  homekit.sh dock vacuum  ·  pause / resume / stop
homekit.sh lock "front door"  ·  homekit.sh unlock "front door"   # only when the user asked
homekit.sh scene "Good Night"  ·  homekit.sh scenes
homekit.sh set lamp "Swing Mode" 1          # any HAP characteristic by its name
```

Friendly properties: `on`, `brightness`, `color`, `hue`, `saturation`, `kelvin`,
`temperature`, `heat`, `cool`, `mode`, `lock`, `open`/`close`, `position`, `tilt`,
`speed`, `swing`, `direction`, `volume`, `mute`, `input`, `key` (TV remote),
`humidity`, `arm` (security), `duration`, `childlock`, `identify`, `action`
(start/stop/pause/resume/dock). If a property isn't supported, the error lists what
the accessory *does* support.

A color or brightness change on a light that's off also turns it on, as the Home app does.

## Reading values

```sh
homekit.sh get "studio orb"            # summary + every derived value
homekit.sh get "studio orb" hex        # just one: hex, rgb, hue, saturation, kelvin,
                                    #   brightness, temperature, humidity, lock, mode…
homekit.sh get "studio orb" --json     # full services/characteristics + Matter clusters
```

`hex` is the full-brightness color and `hexAtBrightness` is scaled by brightness.
`kelvin` is only reported while the light is in white mode (`colorMode`).

## Cameras

```sh
homekit.sh cameras                                       # list
homekit.sh camera snapshot "driveway camera" --copy      # still → file, and onto the clipboard
homekit.sh camera snapshot "driveway camera" --out ~/Desktop/driveway.jpg
homekit.sh camera open "driveway camera"              # live view in a window on the Mac
homekit.sh camera url "driveway camera"                  # local MJPEG + JPEG URLs
```

**There is no RTSP URL for a HomeKit camera.** HomeKit streams are encrypted SRTP
sessions that only Apple's `homed` can open. If the user asks for RTSP, explain that
and offer the `camera url` MJPEG re-stream instead (VLC, ffplay, OBS and browsers play
it). It's 127.0.0.1-only unless the relay is on, in which case it also prints
network URLs with `?token=` for other devices. The camera's own manufacturer app may expose real RTSP.
A snapshot from an unreachable camera comes back `stale` with `capturedAt`; say so.

## Other machines (Windows, Linux, WSL): the relay

The bridge only runs on a Mac. To reach the home from elsewhere, the Mac runs
`homekit.sh relay on`, which prints a URL and token. **Turning the relay on exposes the
home to the network, so only do it when the user asks.** Then:

- Linux / WSL / Git Bash / another Mac: `homekit.sh connect <url> <token>`. Every
  command above then works unchanged. `homekit.sh bridge status` shows `via <url>`
  when you're in remote mode.
- Windows PowerShell: `clients/HomeKit.ps1` takes the same commands
  (`.\HomeKit.ps1 connect <url> <token>`, `.\HomeKit.ps1 set "studio orb" color green`,
  `-Json`).
- Anything with HTTP: `curl -H "Authorization: Bearer $TOKEN" <url>/api/accessories/studio%20orb/hex`,
  `POST <url>/api/accessories/<name>` with `{"color":"green"}`, or `POST <url>/api` with
  any raw request (`{"action":"set","target":…,"props":{…}}`).
- People: the dashboard at `<url>/?token=<token>` in any browser.

Never paste the token into chats, commits or logs beyond what the user asked for.
`homekit.sh relay rotate` replaces it.

## Matter, raw

For anything the friendly verbs don't cover:

```sh
homekit.sh matter "dishwasher"                                   # endpoints, clusters, attributes, commands
homekit.sh matter "dishwasher" invoke "Operational State" Start
homekit.sh matter "oven" invoke 0x56 0 '{"0": 18000}'            # fields keyed by tag
homekit.sh matter "fan" write "Fan Control" "Percent Setting" 40
```

## Safety

- Locks, garage doors, gates, security systems, valves and ovens act on the physical
  world. Change them only when the user explicitly asked for that accessory in this
  conversation, and never as a side effect of a group command.
- Group commands ("all lights") are fine for lights and switches the user named.
- Don't flip things just to test. Use `get`, `find` and `ls` to look around.

## When it fails

- Exit 3 / "the bridge isn't running": `homekit.sh bridge start` (it auto-starts by default).
  If that fails: `~/Desktop/HomeKit.sh/bridge/build.sh --install`.
- Exit 3 in remote mode: the relay is off or the token changed. Ask the user to run
  `homekit.sh relay status` on the Mac and reconnect.
- "no response": the accessory is offline in Home. Report it; retrying won't help.
- Wrong home: `homekit.sh homes`, then `--home "<name>"` or `homekit.sh use "<name>"`.
- Pass `--json` for machine-readable output on any command.