Skip to content
Back to search

homeclaw

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/omarshahine/HomeClaw with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/omarshahine/HomeClaw'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/omarshahine--homeclaw/badge.svg)](/listings/omarshahine--homeclaw)

HTML

<a href="/listings/omarshahine--homeclaw"><img src="/api/listings/omarshahine--homeclaw/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Marketing site with screenshots and full pitch: **[homeclaw.omarknows.app](https://homeclaw.omarknows.app/)**.

Mac App Store (Recommended)

HomeClaw is live on the Mac App Store:

<p> </p>

1. **[Open in the Mac App Store](https://apps.apple.com/us/app/homeclaw/id6759682551?mt=12)** and install 2. Launch HomeClaw -- grant HomeKit access when prompted 3. The menu bar icon appears. Click it to see your connected homes.

App Store builds are fully signed and notarized, so HomeKit works without any developer account setup.

TestFlight Beta

Want early access to in-flight builds before they ship to the App Store?

1. **[Join the TestFlight Beta](https://testflight.apple.com/join/zjSnz8eK)** 2. Install HomeClaw from TestFlight 3. Launch the app -- grant HomeKit access when prompted

TestFlight builds are signed the same way as App Store builds, so HomeKit works out of the box. You'll get new features (like the automations work in v1.0.1) before they hit the App Store.

After installing

Set up your AI integrations:

- **[Claude Desktop](#connecting-an-mcp-client)** -- one-click install from Settings > Integrations, or add the MCP server config manually - **[Claude Code](#using-with-claude-code)** -- install the plugin from GitHub - **[OpenClaw](#using-with-openclaw)** -- one-click install from Settings > Integrations, or set up manually

Build from Source

<details> <summary>Prerequisites and setup for building from source</summary>

Prerequisites

- macOS 26 (Tahoe) or later - Xcode 26+ with Swift 6.2 - [XcodeGen](https://github.com/yonaskolb/XcodeGen): `brew install xcodegen` - Node.js 20+ (for the MCP server wrapper) - **Apple Developer account** with HomeKit capability enabled

> **Why is a developer account required?** Apple does not provide a public HomeKit API for macOS. The only way to access HomeKit is through `HMHomeManager`, which requires the `com.apple.developer.homekit` entitlement and a provisioning profile that covers your Mac's hardware UDID. Apple restricts this entitlement to development signing and App Store distribution -- it cannot be included in Developer ID (notarized) builds. This means every Mac that runs HomeClaw must be registered as a development device in your Apple Developer portal, and the app must be built with your team's signing identity. There is no way around this; it's an Apple platform restriction, not a HomeClaw limitation.

Setup

git clone https://github.com/omarshahine/HomeClaw.git
cd HomeClaw

# Configure your Apple Developer Team ID (one-time setup)
echo "HOMEKIT_TEAM_ID=YOUR_TEAM_ID" > .env.local

# Install Node.js dependencies
npm install

# Build everything and install
scripts/build.sh --release --install

Find your Team ID at [developer.apple.com/account](https://developer.apple.com/account) under Membership Details.

Launch from `/Applications` or: `open "/Applications/HomeClaw.app"`

On first launch, grant HomeKit access when prompted. The menu bar icon appears -- click it to see your connected homes.

> **Note:** Apple restricts the HomeKit entitlement to development signing and App Store distribution. Developer ID builds cannot access HomeKit. See [Why Development Signing?](#why-development-signing) for details.

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 24 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "homeclaw",
  3. "owner": {
  4. "name": "Omar Shahine"
  5. },
  6. "plugins": [
  7. {
  8. "name": "homeclaw",
  9. "source": "./",
  10. "description": "HomeKit smart home control via MCP - control lights, locks, thermostats, and scenes",
  11. "version": "1.0.16",
  12. "keywords": [
  13. "homekit",
  14. "smart-home",
  15. "lights",
  16. "locks",
  17. "thermostats",
  18. "scenes",
  19. "automation"
  20. ],
  21. "category": "iot"
  22. }
  23. ]
  24. }
README.md · README · 1,284 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center"><img src="docs/images/homeclaw-icon.png" width="200" alt="HomeClaw icon"></p>
  2. <h1 align="center">HomeClaw</h1>
  3. <p align="center">
  4. Control your Apple HomeKit smart home from AI assistants, the terminal, and automation tools.
  5. </p>
  6. <p align="center">
  7. <a href="https://apps.apple.com/us/app/homeclaw/id6759682551?mt=12"><img src="https://img.shields.io/badge/Mac%20App%20Store-Download-0d8b8b?logo=apple&logoColor=white&style=for-the-badge" alt="Download on the Mac App Store"></a>
  8. <a href="https://homeclaw.omarknows.app/"><img src="https://img.shields.io/badge/Site-homeclaw.omarknows.app-2c3e50?style=for-the-badge" alt="Website"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
  10. </p>
  11. HomeClaw exposes your HomeKit accessories through a **command-line tool**, a **stdio MCP server**, and plugins for **Claude Code** and **OpenClaw**. It runs as a lightweight macOS menu bar app.
  12. ## Screenshots
  13. <p align="center">
  14. <img src="docs/images/framed-settings.png" width="700" alt="Settings — HomeKit homes and accessories overview">
  15. <br><em>Settings — every preference in one place</em>
  16. </p>
  17. <p align="center">
  18. <img src="docs/images/framed-cli-list.png" width="700" alt="CLI — list every accessory in one command">
  19. <br><em>CLI — every accessory, one command away</em>
  20. </p>
  21. <p align="center">
  22. <img src="docs/images/framed-tui.png" width="700" alt="Terminal UI — accessory tree with live status">
  23. <br><em>Terminal UI — for power users</em>
  24. </p>
  25. ## Why HomeClaw?
  26. Apple HomeKit has no public API, no CLI, and no way to integrate with AI assistants or automation pipelines. HomeClaw bridges that gap with a Mac Catalyst app that talks to HomeKit on your behalf and exposes a clean API surface.
  27. - Ask Claude or OpenClaw to "turn off all the lights" or "set the thermostat to 72"
  28. - Script your smart home from the terminal
  29. - Build automations that go beyond what the Home app offers
  30. - Search and control devices by name, room, category, or semantic type
  31. ## Architecture
  32. ```
  33. Claude Code --> Plugin (.claude-plugin/) --> stdio MCP server (Node.js) --+
  34. Claude Desktop --> stdio MCP server (Node.js) ----------------------------+
  35. OpenClaw --> Plugin (openclaw/) --> homeclaw-cli --------------------------+
  36. v
  37. Unix socket (JSON newline-delimited)
  38. |
  39. HomeClaw (Mac Catalyst app)
  40. +-- HomeKitManager (direct, in-process)
  41. +-- SocketServer (for CLI/MCP clients)
  42. +-- macOSBridge.bundle (NSStatusItem menu bar)
  43. ```
  44. **Single-process design.** Apple's `HMHomeManager` requires a UIKit/Catalyst app with the HomeKit entitlement. By making the entire app Catalyst, HomeKit access is direct (no IPC), signing is unified (single archive), and App Store submission is clean. The `macOSBridge` plugin bundle provides the native macOS menu bar via `NSStatusItem`.
  45. ## Native MCP for Hermes
  46. HomeClaw must be running before connecting. In **Settings → Integrations**, enable **Streamable HTTP MCP**. This persistent setting is **off by default**; turning it off stops the HTTP listener without disabling existing stdio or Unix-socket clients. When enabled, the Catalyst app owns a loopback-only Streamable HTTP endpoint:
  47. ```text
  48. http://127.0.0.1:9090/mcp
  49. ```
  50. Loopback binding prevents remote network access; no bearer token or shell launch is required. Readiness is available at `http://127.0.0.1:9090/healthz`. In Hermes, add:
  51. ```yaml
  52. mcp_servers:
  53. homeclaw:
  54. url: http://127.0.0.1:9090/mcp
  55. timeout: 120
  56. connect_timeout: 30
  57. ```
  58. The stdio MCP server remains supported for Claude Desktop, Claude Code, and OpenClaw. Use the existing `npm run build:mcp` and stdio setup when a client cannot use native HTTP.
  59. ### Native transport development checks
  60. `swift test` covers the CLI package only. To build and execute the full native
  61. Catalyst `HomeClawTests` suite on macOS 26 or later:
  62. ```bash
  63. npm install
  64. node scripts/check-mcp-schema-parity.mjs
  65. xcodegen generate
  66. bash scripts/test-catalyst.sh
  67. ```
  68. Project generation writes `HomeClaw.xcodeproj/project.xcproj` through Apple's
  69. JSON converter. Install Xcode 27.2 or later alongside the pinned 27.1 build
  70. toolchain; the finalizer selects the converter per process and leaves the build
  71. pin and global developer-tools selection unchanged.
  72. The test script saves the xcodebuild log and `.xcresult` under
  73. `.build/catalyst-test-evidence/` and fails on empty or skipped test results. For a
  74. repeat run, set `CATALYST_EVIDENCE_DIR` to a fresh directory. Unit-test hosting
  75. suppresses live HomeKit, socket, and menu-bar startup; these tests are not proof
  76. of HomeKit provisioning or real accessory access.
  77. `lib/schemas.js` is the canonical tool schema. The Swift descriptors are readable
  78. JSON and CI compares every descriptor against the Node export and the XCTest
  79. fixture. After an intentional schema edit, regenerate both reviewed copies with
  80. `node scripts/check-mcp-schema-parity.mjs --write`, then inspect their diff. The
  81. HTTP read-only allowlist remains separate and deny-by-default; adding a tool to
  82. the canonical schema does not expose it over HTTP.
  83. ## Install
  84. Marketing site with screenshots and full pitch: **[homeclaw.omarknows.app](https://homeclaw.omarknows.app/)**.
  85. ### Mac App Store (Recommended)
  86. HomeClaw is live on the Mac App Store:
  87. <p>
  88. <a href="https://apps.apple.com/us/app/homeclaw/id6759682551?mt=12"><img src="https://img.shields.io/badge/Download-Mac%20App%20Store-0d8b8b?logo=apple&logoColor=white&style=for-the-badge" alt="Download on the Mac App Store"></a>
  89. </p>
  90. 1. **[Open in the Mac App Store](https://apps.apple.com/us/app/homeclaw/id6759682551?mt=12)** and install
  91. 2. Launch HomeClaw -- grant HomeKit access when prompted
  92. 3. The menu bar icon appears. Click it to see your connected homes.
  93. App Store builds are fully signed and notarized, so HomeKit works without any developer account setup.
  94. ### TestFlight Beta
  95. Want early access to in-flight builds before they ship to the App Store?
  96. 1. **[Join the TestFlight Beta](https://testflight.apple.com/join/zjSnz8eK)**
  97. 2. Install HomeClaw from TestFlight
  98. 3. Launch the app -- grant HomeKit access when prompted
  99. TestFlight builds are signed the same way as App Store builds, so HomeKit works out of the box. You'll get new features (like the automations work in v1.0.1) before they hit the App Store.
  100. ### After installing
  101. Set up your AI integrations:
  102. - **[Claude Desktop](#connecting-an-mcp-client)** -- one-click install from Settings > Integrations, or add the MCP server config manually
  103. - **[Claude Code](#using-with-claude-code)** -- install the plugin from GitHub
  104. - **[OpenClaw](#using-with-openclaw)** -- one-click install from Settings > Integrations, or set up manually
  105. ### Build from Source
  106. <details>
  107. <summary>Prerequisites and setup for building from source</summary>
  108. #### Prerequisites
  109. - macOS 26 (Tahoe) or later
  110. - Xcode 26+ with Swift 6.2
  111. - [XcodeGen](https://github.com/yonaskolb/XcodeGen): `brew install xcodegen`
  112. - Node.js 20+ (for the MCP server wrapper)
  113. - **Apple Developer account** with HomeKit capability enabled
  114. > **Why is a developer account required?** Apple does not provide a public HomeKit API for macOS. The only way to access HomeKit is through `HMHomeManager`, which requires the `com.apple.developer.homekit` entitlement and a provisioning profile that covers your Mac's hardware UDID. Apple restricts this entitlement to development signing and App Store distribution -- it cannot be included in Developer ID (notarized) builds. This means every Mac that runs HomeClaw must be registered as a development device in your Apple Developer portal, and the app must be built with your team's signing identity. There is no way around this; it's an Apple platform restriction, not a HomeClaw limitation.
  115. #### Setup
  116. ```bash
  117. git clone https://github.com/omarshahine/HomeClaw.git
  118. cd HomeClaw
  119. # Configure your Apple Developer Team ID (one-time setup)
  120. echo "HOMEKIT_TEAM_ID=YOUR_TEAM_ID" > .env.local
  121. # Install Node.js dependencies
  122. npm install
  123. # Build everything and install
  124. scripts/build.sh --release --install
  125. ```
  126. Find your Team ID at [developer.apple.com/account](https://developer.apple.com/account) under Membership Details.
  127. Launch from `/Applications` or: `open "/Applications/HomeClaw.app"`
  128. On first launch, grant HomeKit access when prompted. The menu bar icon appears -- click it to see your connected homes.
  129. > **Note:** Apple restricts the HomeKit entitlement to development signing and App Store distribution. Developer ID builds cannot access HomeKit. See [Why Development Signing?](#why-development-signing) for details.
  130. </details>
  131. ## MCP Tools
  132. The stdio MCP server wraps `homeclaw-cli` and exposes these tools:
  133. | Tool | Description |
  134. |------|-------------|
  135. | `homekit_status` | Check bridge connectivity and accessory count |
  136. | `homekit_accessories` | List, get details, search, or control accessories |
  137. | `homekit_rooms` | List rooms and their accessories |
  138. | `homekit_scenes` | List, get details, trigger, import, or delete scenes |
  139. | `homekit_device_map` | LLM-optimized device map with semantic types and aliases |
  140. | `homekit_manage` | Manage home structure: rename accessories, individual services, and rooms; set a switch/outlet's Display As; list and manage accessory groups; create/remove rooms and zones, manage zone membership |
  141. | `homekit_automations` | Manage automations: list, create (button, sensor or time-of-day triggers with conditions, weekdays and auto-revert), edit in place, add conditions, link to scenes, enable/disable, plan accessory replacement |
  142. | `homekit_events` | Query recent HomeKit events (characteristic changes, reachability changes, scene triggers, control actions) |
  143. | `homekit_webhook` | Manage webhook configuration: setup (configure + auto-test), test, reset circuit breaker, status |
  144. | `homekit_config` | View or update configuration (set active home, filtering) |
  145. ### Connecting an MCP Client
  146. Any MCP-compatible client can connect via the **stdio server**, which wraps `homeclaw-cli` and requires no authentication (the HomeClaw app must be running for the socket). Add this to your MCP client config (e.g. `claude_desktop_config.json`):
  147. ```json
  148. {
  149. "mcpServers": {
  150. "homeclaw": {
  151. "command": "node",
  152. "args": ["/Applications/HomeClaw.app/Contents/Resources/mcp-server.js"]
  153. }
  154. }
  155. }
  156. ```
  157. The `mcp-server.js` is bundled inside the app. You can also use the Integrations tab in Settings to install this automatically.
  158. ## CLI
  159. The `homeclaw-cli` command-line tool communicates directly over the Unix domain socket. All read commands support `--json` for machine-readable output. Day-to-day commands also accept `--home <name-or-uuid>` to target a specific HomeKit home without changing the configured default (`config --default-home`).
  160. ```bash
  161. # List accessories
  162. homeclaw-cli list
  163. homeclaw-cli list --room "Kitchen"
  164. homeclaw-cli list --category thermostat
  165. homeclaw-cli list --home "Cabin" --room "Kitchen" # Scope to a home (name or UUID)
  166. # Control devices
  167. homeclaw-cli set "Living Room Light" brightness 75
  168. homeclaw-cli set "Front Door Lock" lock_target_state locked
  169. homeclaw-cli set "Thermostat" target_temperature 72
  170. homeclaw-cli set "Kitchen Light" power true --home "Cabin"
  171. # Disambiguate when a characteristic exists on multiple services (e.g. bridged TVs)
  172. homeclaw-cli set "TV" active 0 --service-type 000000D8-0000-1000-8000-0026BB765291
  173. # Get detailed device info
  174. homeclaw-cli get "Kitchen Light" --json
  175. homeclaw-cli get "Kitchen Light" --home "Cabin"
  176. # Search (optionally scoped to one home)
  177. homeclaw-cli search "bedroom" --category lightbulb
  178. homeclaw-cli search "lamp" --home "Cabin"
  179. # Scenes
  180. homeclaw-cli scenes
  181. homeclaw-cli scenes --home "Cabin"
  182. homeclaw-cli get-scene "Good Night" --json # Full detail: all actions
  183. homeclaw-cli trigger "Good Night"
  184. homeclaw-cli trigger "Good Night" --home "Cabin"
  185. # Scene management
  186. homeclaw-cli delete-scene "Old Scene"
  187. homeclaw-cli import-scene scene.json --dry-run # Preview before creating
  188. homeclaw-cli import-scene scene.json # Create scene from JSON
  189. homeclaw-cli assign-rooms rooms.json --dry-run # Preview room assignments
  190. homeclaw-cli assign-rooms rooms.json # Bulk-assign accessories to rooms
  191. # Home management
  192. homeclaw-cli rename "Front Door" "Front Door Lock" # Rename accessory
  193. homeclaw-cli rename "Dual Relay" "Downlight 2" --service-name "Switch 2" # Rename one gang's tile
  194. homeclaw-cli set-display-as "Dual Relay" light --service-index 1 # Display As: light / fan / switch / outlet / default
  195. homeclaw-cli groups # Home app accessory groups and members
  196. homeclaw-cli groups create "Ceiling Lights" "Downlight 1" <service-uuid> # One tile for several lights (same kind)
  197. homeclaw-cli groups add "Ceiling Lights" "Stairs LED" # Also: remove / rename / delete, --dry-run
  198. homeclaw-cli rename-room "Bedroom" "Primary Bedroom" # Rename room
  199. homeclaw-cli create-room "Nursery" # Create room
  200. homeclaw-cli remove-room "Old Room" # Remove room
  201. homeclaw-cli remove-accessory "Broken Sensor" # Remove accessory
  202. homeclaw-cli create-zone "Upstairs" # Create zone
  203. homeclaw-cli remove-zone "Old Zone" # Remove zone
  204. homeclaw-cli add-room-to-zone "Bedroom" "Upstairs" # Add room to zone
  205. homeclaw-cli remove-room-from-zone "Bedroom" "Upstairs" # Remove room from zone
  206. homeclaw-cli rename "Front Door" "New Name" --dry-run # Preview any mutation
  207. # Automations (button programming)
  208. homeclaw-cli automations # List all automations
  209. homeclaw-cli automations get "<name-or-uuid>" # Detail view
  210. # Scene-based: trigger an existing scene
  211. homeclaw-cli automations create --name "Gym Lights" \
  212. --accessory "Gym Button" --scene "Gym On" --press single
  213. # Inline actions: use UUIDs for target accessories to avoid name collisions
  214. homeclaw-cli automations create --name "Sarah's Room Open" \
  215. --accessory "Office Button" \
  216. --action "BE21C139-413A-50F9-B97F-B9BDA06302A8:power:true" \
  217. --action "52195C6F-6FAA-5E52-AA56-840A6605EEAA:target_position:100" \
  218. --press single --service-index 1
  219. # Multi-button preview
  220. homeclaw-cli automations create --name "Open Blinds" \
  221. --accessory "Blinds Button" --scene "Open" \
  222. --service-index 1 --dry-run
  223. # One gang of a multi-gang accessory: JSON row form (see "Targeting one gang" below)
  224. homeclaw-cli automations create --name "Table Light Off" \
  225. --accessory "Dining Button" --press single \
  226. --action-json '{"accessory":"<uuid>","property":"power","value":"false","service_index":2}'
  227. homeclaw-cli automations delete "<name-or-uuid>" # Delete automation
  228. homeclaw-cli automations enable "<name-or-uuid>" # Enable
  229. homeclaw-cli automations disable "<name-or-uuid>" # Disable
  230. # Edit in place (keeps the UUID; only the options passed change)
  231. homeclaw-cli automations edit "Coffee Maker" --time 06:45 --days mon,tue,wed,thu,fri,sat
  232. homeclaw-cli automations edit "Hall Motion" --time-after sunset --time-before sunrise --duration 300
  233. homeclaw-cli automations edit "Porch Lights" --condition "Front Door:contact_state:0" --dry-run
  234. homeclaw-cli automations edit "Porch Lights" --name "Porch at Dusk" --clear-duration
  235. # Replacing an accessory: plan which automation actions move (writes nothing)
  236. homeclaw-cli automations migrate-actions --replace-accessory "<old-uuid>=<new-uuid>[,<new-uuid>]"
  237. homeclaw-cli automations migrate-actions --replace-accessory "<old>=<new>" --automation "<name-or-uuid>" --json
  238. homeclaw-cli automations migrate-actions --replace-accessory "<old>=<new>" --apply # Writes visible scenes only
  239. # LLM-optimized device map
  240. homeclaw-cli device-map
  241. homeclaw-cli device-map --home "Cabin"
  242. # Status and configuration
  243. homeclaw-cli status
  244. homeclaw-cli config --default-home "Main House"
  245. homeclaw-cli config --filter-mode allowlist
  246. homeclaw-cli config --list-devices
  247. # Event log
  248. homeclaw-cli events # Recent events (last 50)
  249. homeclaw-cli events --since 1h # Events from the last hour
  250. homeclaw-cli events --since 2d --json # Last 2 days, JSON output
  251. homeclaw-cli events --type scene_triggered # Filter by event type
  252. homeclaw-cli events --type reachability_change --since 1d # When accessories dropped off or came back
  253. # Webhook configuration
  254. homeclaw-cli config --webhook-url "http://127.0.0.1:18789"
  255. homeclaw-cli config --webhook-token "your-secret-token"
  256. homeclaw-cli config --webhook-enabled true
  257. homeclaw-cli config --webhook-test # Send test event, show HTTP response
  258. homeclaw-cli config --webhook-reset # Reset circuit breaker without toggling
  259. # Webhook triggers
  260. homeclaw-cli triggers # List all triggers
  261. homeclaw-cli triggers add --label "Front Door" --accessory-id "<uuid>"
  262. homeclaw-cli triggers add --label "Mailbox Open" --accessory-id "<uuid>" --characteristic contact_state
  263. homeclaw-cli triggers add --label "Accessory offline" --characteristic reachable --value false
  264. homeclaw-cli triggers update "<trigger-id>" --wake-mode now
  265. homeclaw-cli triggers remove "<trigger-id>"
  266. # Dry-run mutations (validate without actuating)
  267. homeclaw-cli set "Front Door" lock_target_state locked --dry-run
  268. homeclaw-cli delete-scene "Movie Night" --dry-run
  269. # Auto-JSON: all commands output JSON when piped or when env var is set
  270. homeclaw-cli status | jq . # Auto-detects non-TTY
  271. OUTPUT_FORMAT=json homeclaw-cli list # Force JSON via env var
  272. ```
  273. ### Button Programming Notes
  274. **Inline vs scene:** Use `--action` for simple button-to-device mappings. This creates a scene named after the automation. Use `--scene` to trigger an existing scene instead. Note: Apple's Home app uses a private API for hidden automation-only action sets; inline actions created via HomeClaw will appear as visible scenes in the Home app.
  275. Doorbells exposing `input_event` on a HomeKit Doorbell service also support button automations (for example, `--accessory "Front Doorbell" --press single`). A lone doorbell needs no `--service-index`. When selecting among multiple button services, the index must match an actual `ServiceLabelIndex`; it is never an array position or an assumed doorbell index. Ambiguous matches are rejected.
  276. **Button modes:** Some buttons (like Aqara AR009) support fast mode (2 buttons, single press each, instant response) or multi-event mode (1 button, single/double/long press, ~300ms delay). Use `--service-index` to target a specific button in fast mode.
  277. Note that `--service-index` on `automations create` picks the **trigger** button. The service an inline action or condition writes to is picked per row, as below.
  278. #### Targeting one gang of a multi-gang accessory
  279. A dual relay or a 3-gang switch is one accessory with several services that all carry `power`. Any action or condition row can pick one of them with `service_name`, `service_id`, or `service_index` (the same selectors `set` takes). The positional `accessory:property:value` form has no room for a fourth field (it splits on the first two colons so values like `22:30` survive), so use the JSON row flags instead:
  280. ```bash
  281. # Turn off both gangs of one dual relay
  282. homeclaw-cli automations create --name "Dining Unoccupied" \
  283. --accessory "Dining FP2" --characteristic occupancy_detected --trigger-value false \
  284. --action-json '{"accessory":"ADA239D3-...","property":"power","value":"false","service_index":1}' \
  285. --action-json '{"accessory":"ADA239D3-...","property":"power","value":"false","service_name":"Table Light"}' \
  286. --dry-run
  287. # Conditions take the same keys (--condition-json on create / create-time, flags on add-condition)
  288. homeclaw-cli automations add-condition "Porch Lights" \
  289. --accessory "ADA239D3-..." --property power --value true --service-index 2
  290. ```
  291. `--action-json` / `--condition-json` are repeatable, accept `accessory`, `property` (or `characteristic`), `value`, `room`, and the three selectors, and reject unknown keys. Rules for every surface (CLI, MCP, scene JSON):
  292. - **With a selector**, the row resolves to exactly that service, or fails with an error listing the services that carry the property. It never falls back to another gang.
  293. - **Without a selector** on a property that exists on several services, HomeClaw keeps the old behavior (the first service) so existing scene JSON keeps working, but the response carries a `warnings` entry naming every candidate. Add a selector to silence it.
  294. - Two actions on the same accessory and property are allowed when they target different services. The same service twice is rejected.
  295. - `get-scene`, `automations get`, and dry-run previews emit `service_name`, `service_id`, and `service_index` on rows whose accessory has more than one service carrying that property, so their JSON round-trips through `import-scene` / `update-scene` without collapsing gangs. Rows on single-service accessories are unchanged.
  296. ### Editing an Automation in Place
  297. `automations edit` changes an existing automation without deleting it, so its UUID stays the same and button bindings, Siri references and integrations keep working. Only the options you pass change:
  298. | Option | Effect | Clear with |
  299. |--------|--------|------------|
  300. | `--name` | Rename (the only edit Home app timer automations accept) | |
  301. | `--time` | Replace the trigger event(s) with a time of day (same values as `create-time`) | |
  302. | `--days` | Replace the weekday gate | `--every-day` |
  303. | `--condition` / `--condition-json` | Replace **all** characteristic conditions | `--clear-conditions` |
  304. | `--time-after` / `--time-before` | Replace the **whole** time window | `--clear-time-window` |
  305. | `--duration` | Set the auto-revert | `--clear-duration` |
  306. Conditions of a kind you don't replace are kept as they are, including ones HomeClaw can't decode, so changing the time window never drops a condition the Home app wrote. A time-based result without a weekday gate gets all 7 days filled in, as on `create-time`.
  307. Everything is validated before the first write. `--dry-run` shows `before`, `planned` and `changes`. A real run writes the predicate, weekdays, events, end events and name in that order; if a step fails, the steps already written are restored and the error says which. Afterwards the automation is re-read and compared with the plan: `"verified": false` lists the `mismatches`. Over MCP this is `homekit_automations` with `action: "edit"` (`new_name`, `time`, `weekdays`, `conditions`, `time_after`, `time_before`, `duration_seconds`, `clear_duration`; an empty array clears).
  308. ### Replacing an Accessory in Automations
  309. You swapped a bulb, a switch, or a shade. Now every automation that used the old one needs the new one. `automations migrate-actions` plans that move and tells you, per action set, what it can and can't do.
  310. Each action set an automation runs is one of two kinds:
  311. | Kind | What it is | Can HomeClaw edit it? |
  312. |------|------------|-----------------------|
  313. | `visible_scene` | A scene in the Home app's Scenes list that an automation points at | Yes, in place (the scene keeps its UUID). But it's **shared**: editing it changes every other automation that uses it, and the scene tile itself. The plan lists those in `shared_with`. |
  314. | `hidden` | The action set the Home app creates inside one automation (most button and sensor automations made in the Home app) | **No.** Apple's HomeKit daemon only lets apps with Apple's private `com.apple.homekit.private-spi-access` entitlement write these. No third-party app can get it. See [docs/PRIVATE_API.md](docs/PRIVATE_API.md). |
  315. So hidden sets always come back `"status": "unsupported"` with `"reason": "hidden_action_set_requires_private_spi"`, the exact accessories and values to change, and `manual_steps` you (or your assistant) can follow in the Home app: open the automation, remove the old accessory, add the new one, set each value, tap Done. Rerun the dry run afterwards and the automation drops out of the plan.
  316. For each old action, the plan finds the same characteristic type (power, brightness, color temperature, hue, saturation, position, and anything else) on each replacement. A visible set is `blocked` instead of `supported` when no replacement can take a characteristic (it would be dropped), when a replacement has several services carrying it (the issue lists each candidate's `service_name`, `service_id` and `service_index`; migrate-actions doesn't take selectors itself, so edit that scene with `update-scene` rows that carry one), or when the new action would conflict with one already in the scene.
  317. It's a dry run unless you pass `--apply`. With `--apply`, only `supported` visible scenes are written: the rollback snapshot (every current action) is logged and returned first, the new actions are added, the old ones removed, and the scene is re-read and checked to contain exactly the planned actions. Triggers, conditions, enabled state and recurrence are never touched. A failed or unverified write exits non-zero and reports what was written.
  318. Automations that are only *triggered* by the old accessory (a motion sensor that turns on a light) are listed too, with `"trigger_only": true` and no action sets: there's nothing to move, but that trigger stops firing once the old accessory is gone, and this command never rewrites triggers. Recreate those in the Home app.
  319. Migrate before you remove the old accessory from HomeKit. HomeKit usually drops a removed accessory's scene actions, and then there's nothing left to move. An old accessory that's already gone can still be named by UUID.
  320. ### Interactive TUI
  321. ```bash
  322. homeclaw-cli ui
  323. ```
  324. Launches a full-screen, keyboard-driven view of your home. Browse rooms and accessories, see live state at a glance, and toggle anything that has a binary state (lights, switches, fans, outlets, locks, blinds).
  325. ```
  326. 🦞 HomeClaw 21 rooms · 112 accessories
  327. ┌──────────────────────────────────────────────────────────────────────┐
  328. │ ▾ Living Room (4) │
  329. │ ├─ ● Floor Lamp On │
  330. │ ├─ ● TV Light Strip On │
  331. │ ├─ ◐ Thermostat 70.5°F │
  332. │ └─ ○ Window Blinds 100% │
  333. │ │
  334. │ ▾ Kitchen (3) │
  335. │ ├─ ○ Counter Light Off │
  336. │ ... │
  337. └──────────────────────────────────────────────────────────────────────┘
  338. ^D quit ↑↓ navigate Enter toggle
  339. ```
  340. | Key | Action |
  341. |---|---|
  342. | `↑` `↓` | Navigate between accessories |
  343. | `Enter` | Toggle the focused accessory (lights/switches/outlets/fans flip on↔off, locks flip locked↔unlocked, blinds flip 0%↔100%) |
  344. | `Ctrl-D` | Quit |
  345. State color coding: lights on are yellow, outlets/switches cyan, fans blue, locks green when locked / red when unlocked, motion red, sensors cyan, off/idle dim.
  346. The TUI works over SSH (no AppKit assumptions), runs against the same Unix socket as the rest of the CLI, and respects demo mode — launch HomeClaw with `--ui-test-demo` to render a synthetic home for screenshots or demos. Built on [SwiftTUI](https://github.com/rensbreur/SwiftTUI). Scene picker, search, and help overlay are tracked in [#53](https://github.com/omarshahine/HomeClaw/issues/53) — they need a different framework's key handling and will land when SwiftTUI gains app-level key bindings (or we switch).
  347. ## Using with Claude Code
  348. HomeClaw integrates with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) as a **plugin** that provides MCP tools and a HomeKit skill for richer natural language understanding.
  349. ### Installing the Plugin
  350. Install from a local clone or directly from GitHub.
  351. **From a local clone:**
  352. ```bash
  353. # Clone if you haven't already
  354. git clone https://github.com/omarshahine/HomeClaw.git ~/GitHub/HomeClaw
  355. # Inside Claude Code, register the marketplace and install
  356. /plugin marketplace add ~/GitHub/HomeClaw
  357. /plugin install homeclaw@homeclaw
  358. ```
  359. **From GitHub (no local clone needed):**
  360. ```bash
  361. # Inside Claude Code, add the GitHub repo as a marketplace
  362. /plugin marketplace add https://github.com/omarshahine/HomeClaw
  363. # Install the plugin
  364. /plugin install homeclaw@homeclaw
  365. ```
  366. After installing, restart Claude Code. Then just ask:
  367. > "Turn on the kitchen lights and set them to 50% brightness"
  368. > "Lock all the doors"
  369. > "What's the thermostat set to?"
  370. > "Run the movie time scene"
  371. > "Which lights are on in the living room?"
  372. ### Verifying the Connection
  373. After installing, verify Claude can reach HomeKit:
  374. ```bash
  375. # Check MCP server status inside Claude Code
  376. /mcp
  377. ```
  378. ## Using with OpenClaw
  379. HomeClaw includes an [OpenClaw](https://openclaw.ai) plugin that registers a HomeKit skill on the gateway. The skill calls `homeclaw-cli` by name, so it must be in your PATH.
  380. ### Same-Mac Install (Recommended)
  381. If HomeClaw and OpenClaw run on the same Mac, use the one-click installer:
  382. 1. Open **Settings > Integrations** and click **Install** in the OpenClaw section.
  383. This handles all four steps automatically: installs the plugin, enables it, symlinks `homeclaw-cli` into your PATH, and restarts the gateway.
  384. Or from the terminal:
  385. ```bash
  386. # 1. Install the plugin from the bundled files
  387. openclaw plugins install "/Applications/HomeClaw.app/Contents/Resources/openclaw/"
  388. openclaw plugins enable homeclaw
  389. # 2. Symlink the CLI into PATH (the skill calls homeclaw-cli by name)
  390. # Apple Silicon (M1/M2/M3/M4):
  391. ln -sf '/Applications/HomeClaw.app/Contents/MacOS/homeclaw-cli' /opt/homebrew/bin/homeclaw-cli
  392. # Intel:
  393. ln -sf '/Applications/HomeClaw.app/Contents/MacOS/homeclaw-cli' /usr/local/bin/homeclaw-cli
  394. # 3. Restart the gateway to load the plugin
  395. openclaw gateway restart
  396. ```
  397. ### Remote Gateway
  398. If OpenClaw runs on a different machine:
  399. ```bash
  400. # Clone the repo on the gateway
  401. git clone https://github.com/omarshahine/HomeClaw.git ~/GitHub/HomeClaw
  402. # Install the plugin
  403. openclaw plugins install ~/GitHub/HomeClaw/openclaw
  404. openclaw plugins enable homeclaw
  405. # Symlink the CLI into PATH
  406. ln -sf /path/to/homeclaw-cli /opt/homebrew/bin/homeclaw-cli
  407. # Restart the gateway
  408. openclaw gateway restart
  409. ```
  410. > **Note:** The `homeclaw-cli` binary must be accessible from the gateway (in PATH), and the HomeClaw app must be running on the same Mac (connected via Unix socket).
  411. ### Enabling Control Tools
  412. The plugin registers 20 agent tools. The read-only ones (`homekit_status`, `homekit_device_map`, `homekit_list`, `homekit_get`, `homekit_search`, `homekit_scenes`, `homekit_get_scene`, `homekit_events`, `homekit_groups`, `homekit_automations_list`, `homekit_automations_get`) are on by default, including under the `coding` and `messaging` tool profiles.
  413. The nine tools that can change your home (`homekit_set`, `homekit_trigger`, `homekit_import_scene`, `homekit_delete_scene`, `homekit_rename`, `homekit_set_display_as`, `homekit_manage_group`, `homekit_automations_create`, `homekit_automations_migrate_actions`) are **optional**: OpenClaw hides them until you opt in. To allow all HomeClaw tools, add the plugin id to `tools.alsoAllow` in your OpenClaw config:
  414. ```json
  415. {
  416. "tools": {
  417. "alsoAllow": ["homeclaw"]
  418. }
  419. }
  420. ```
  421. List individual tool names instead of `homeclaw` to enable only some of them, then restart the gateway.
  422. ## Supported Accessories
  423. HomeClaw supports the full range of HomeKit accessory categories:
  424. | Category | Controllable Characteristics |
  425. |----------|------------------------------|
  426. | **Lights** | power, brightness (0-100), hue (0-360), saturation (0-100), color temperature (140-500 mireds) |
  427. | **Thermostats** | target temperature, HVAC mode (off/heat/cool/auto), target humidity |
  428. | **Locks** | lock/unlock (accepts `locked`, `unlocked`, `0`, `1`) |
  429. | **Doors & Garage Doors** | open/close, obstruction detection (read-only) |
  430. | **Fans** | active, rotation speed, rotation direction, swing mode |
  431. | **Window Coverings** | target position (0-100%) |
  432. | **Switches & Outlets** | power on/off |
  433. | **Sensors** | motion, contact, temperature, humidity, light level, battery (all read-only) |
  434. | **Doorbells** | ring detection via input_event (single/double/long press), motion (read-only) |
  435. | **Programmable Switches** | button press detection (single/double/long press) (read-only) |
  436. | **Scenes** | trigger by name or UUID, inspect actions, import from JSON, delete by name or UUID |
  437. ### Scene Import Format
  438. The `import-scene` command accepts a JSON file defining a scene and its actions:
  439. ```json
  440. {
  441. "name": "Movie Night",
  442. "actions": [
  443. {"accessory": "Living Room Light", "room": "Living Room", "property": "brightness", "value": "30%"},
  444. {"accessory": "TV Backlight", "room": "Living Room", "property": "power_state", "value": "ON"},
  445. {"accessory": "Overhead", "room": "Living Room", "property": "power_state", "value": "OFF"}
  446. ]
  447. }
  448. ```
  449. Action objects also accept `characteristic` as an alias for `property` (read commands emit `characteristic`, so their output round-trips as input).
  450. To target one gang of a multi-gang accessory, add `service_name`, `service_id`, or `service_index` to the action (`service_index` may be a JSON number or a string). `get-scene --json` emits these on exactly the rows that need them, so its output can be edited and fed back to `update-scene`:
  451. ```json
  452. {
  453. "id": "D47A94C9-BCCA-553A-AA3C-E756E91D22FE",
  454. "actions": [
  455. {"accessory_id": "ADA239D3-...", "property": "power", "value": "0", "service_name": "Covelight", "service_index": "1"},
  456. {"accessory_id": "ADA239D3-...", "property": "power", "value": "0", "service_name": "Table Light", "service_index": "2"}
  457. ]
  458. }
  459. ```
  460. See [Targeting one gang of a multi-gang accessory](#targeting-one-gang-of-a-multi-gang-accessory) for the resolution and warning rules.
  461. The `assign-rooms` command accepts a JSON file mapping accessories to rooms. Use `uuid` for precise matching when multiple accessories share the same name (e.g., fan + light from a ceiling fan). A name that matches several accessories is skipped with status `ambiguous` rather than guessed. Every other command that takes an accessory name (including scene import/update actions and automation conditions) fails on a duplicate before changing anything, and lists each match's room and UUID:
  462. ```json
  463. [
  464. {"accessory": "Kitchen Light", "room": "Kitchen"},
  465. {"uuid": "790A359D-27A6-5738-A92E-F4380CC6BA07", "room": "Front Door"},
  466. {"accessory": "Desk Lamp", "room": "Office"}
  467. ]
  468. ```
  469. The same array wrapped as `{"assignments": [...]}` is also accepted.
  470. All file-taking commands (`import-scene`, `update-scene`, `assign-rooms`) accept `-` in place of the file path to read JSON from stdin — the recommended path for the sandboxed App Store build, which can only read files from its own container:
  471. ```bash
  472. echo '[{"accessory": "Desk Lamp", "room": "Office"}]' | homeclaw-cli assign-rooms -
  473. ```
  474. Both commands support `--dry-run` to preview changes without modifying HomeKit.
  475. ## Menu Bar App
  476. The menu bar provides at-a-glance status and quick actions:
  477. - **HomeKit connection status** -- shows home names when connected, or error states with reasons
  478. - **Launch at Login** toggle
  479. - **Settings** link and **Quit**
  480. ## Settings
  481. Five configuration tabs accessible from the menu bar:
  482. | Tab | Features |
  483. |-----|----------|
  484. | **HomeKit** | Connection status, home list with accessory and room counts, active home selector |
  485. | **Devices** | Filter mode (all/allowlist), per-device toggles with category icons and state badges, grouped by room, search, bulk select/deselect |
  486. | **Event Log** | Enable/disable event logging, configure file rotation (size limit + backup count), view storage stats, purge logs, reveal in Finder |
  487. | **Webhook** | Configure webhook base URL + bearer token, select which scenes and accessories trigger webhooks with category icons and state badges. Accessories with multiple characteristics (e.g., a sensor with both contact and motion) show individual toggles per characteristic; battery characteristics are excluded. Per-trigger delivery mode (Batched/Immediate). Circuit breaker banners with Reset button, delivery stats, and last HTTP status. Test webhook connectivity from CLI or manage triggers via `homeclaw-cli triggers`. |
  488. | **Integrations** | One-click install for Claude Desktop, Claude Code plugin detection, OpenClaw gateway setup |
  489. ### HomeKit
  490. View connection status, browse your homes, and select which home is active for all MCP and CLI commands.
  491. <p align="center"><img src="docs/images/settings-homekit.png" width="500" alt="HomeKit settings tab"></p>
  492. ### Devices
  493. Control which accessories are exposed to MCP clients and the CLI. Switch between **All Accessories** (everything visible) and **Selected Only** (allowlist mode). Accessories are grouped by room with a search filter and room-level toggles for quick bulk selection.
  494. <p align="center"><img src="docs/images/settings-devices.png" width="500" alt="Devices settings tab"></p>
  495. ### Integrations
  496. Install and manage connections to AI assistants. The app detects existing configurations and guides you through setup:
  497. - **Claude Desktop** -- one-click install of the bundled stdio MCP server (requires Node.js)
  498. - **Claude Code** -- detects the installed plugin (`homeclaw@homeclaw`)
  499. - **OpenClaw** -- detects plugin configuration on the remote gateway and provides setup instructions
  500. <p align="center"><img src="docs/images/settings-integrations.png" width="500" alt="Integrations settings tab"></p>
  501. ## Event Log
  502. HomeClaw records all HomeKit events to a JSONL file in `~/Library/Application Support/HomeClaw/events.jsonl`. Events include characteristic changes (a light turned on), reachability changes (an accessory became unreachable or came back), scene triggers, and control actions from the CLI or MCP.
  503. ### Configuration
  504. Open **Settings > Event Log** to configure:
  505. - **Enable/disable** event logging
  506. - **Max file size** (10-500 MB) -- when the log reaches this size, it's rotated
  507. - **Rotated backups** (0-10) -- how many old log files to keep before deleting the oldest
  508. - **Purge** -- delete all event log files
  509. - **Show in Finder** -- reveal the log directory
  510. Or configure via CLI:
  511. ```bash
  512. homeclaw-cli events # Show recent events
  513. homeclaw-cli events --since 1h # Last hour
  514. homeclaw-cli events --type characteristic_change # Filter by type
  515. homeclaw-cli events --limit 200 --json # JSON output
  516. ```
  517. Event types: `characteristic_change`, `scene_triggered`, `accessory_controlled`, `homes_updated`, `reachability_change`
  518. A `reachability_change` event is logged when HomeKit reports that an accessory became reachable or unreachable. Repeated reports with no change are dropped.
  519. ```json
  520. {
  521. "type": "reachability_change",
  522. "timestamp": "2026-09-28T04:20:09Z",
  523. "accessory": { "id": "…", "name": "B1", "room": "Kids", "matter_node_id": "000000000000002A" },
  524. "reachable": false,
  525. "home": { "id": "…", "name": "Home" }
  526. }
  527. ```
  528. `accessory.matter_node_id` appears only for Matter accessories, and `home` only when the accessory's home is known.
  529. ### Matter node ids
  530. `list`, `search`, `get` and `device-map` include `matter_node_id` for Matter accessories. It is the node id Apple Home assigned on its Matter fabric, written as 16 uppercase hex digits (a string, so the 64-bit value is not rounded by JSON parsers). Non-Matter accessories omit the key.
  531. A Matter device advertises itself over mDNS as `<compressed fabric id>-<node id>`, so the node id joins a HomeKit accessory to its network entry:
  532. ```bash
  533. homeclaw-cli get "B1" --json | jq -r .matter_node_id # e.g. 000000000000002A
  534. dns-sd -B _matter._tcp # instance names end in -<node id>
  535. ```
  536. An unreachable accessory whose node id is missing from `dns-sd` output has dropped off the network (for Thread, the mesh). One that is still advertised points at the controller side instead.
  537. The `--since` flag accepts ISO 8601 timestamps or duration shorthand: `1h`, `30m`, `2d`.
  538. ## Webhook
  539. HomeClaw pushes HomeKit events to [OpenClaw](https://openclaw.ai) via **mapped webhooks**. Only accessories and scenes with configured triggers fire webhooks -- untriggered events are logged to disk but not pushed. Reachability changes are opt-in: they fire only triggers whose characteristic is `reachable` (optionally with value `false` for drops only, and an accessory id for one device). Accessory triggers without that characteristic are not fired by reachability changes, so a flapping accessory does not flood them. A dedicated HomeClaw agent receives all events, classifies them by severity, and escalates noteworthy ones to the main agent.
  540. > **Note:** OpenClaw 2026.3.x has a known bug where `/hooks/wake` silently drops events ([#33271](https://github.com/openclaw/openclaw/issues/33271)). HomeClaw uses **mapped webhooks** (`/hooks/homeclaw`) which route through `hooks.mappings` and are **not affected**.
  541. ### How It Works
  542. HomeClaw POSTs all triggered events to a single mapped endpoint: `/hooks/homeclaw`. OpenClaw's `hooks.mappings` config resolves the `"homeclaw"` key and routes each event to a **dedicated HomeClaw agent** that classifies and triages events.
  543. ```
  544. HomeKit event --> HomeClaw event logger --> POST /hooks/homeclaw
  545. --> OpenClaw hooks.mappings --> HomeClaw Agent (dedicated)
  546. --> Classifies: CRITICAL / NOTABLE / AMBIENT
  547. --> If notable/critical: a2a to main agent
  548. --> If ambient: log to agent memory only
  549. ```
  550. HomeClaw doesn't need to know about `agentId`, `channel`, or `sessionKey` -- all routing intelligence lives in the OpenClaw config.
  551. ### Trigger Delivery Modes
  552. Each trigger has a **delivery mode** that controls timing:
  553. | Mode | Behavior | Set via |
  554. |------|----------|---------|
  555. | **Batched** (default) | Event queued until next heartbeat cycle | Settings UI segmented control |
  556. | **Immediate** | Event delivered right away | Settings UI segmented control |
  557. In **Settings > Webhook**, each enabled trigger shows a **Batched / Immediate** picker. Use Immediate for events you want to react to right away (leak sensors, door locks, scene triggers). Use Batched for ambient events (light toggles, temperature changes) to avoid noise.
  558. ### Setup with AI Assistant
  559. Paste this prompt into **OpenClaw** or **Claude Code** to configure webhooks end-to-end. The prompt is idempotent -- it verifies each step and skips anything already configured:
  560. > **Prerequisites:** HomeClaw must be installed and running (menu bar icon visible). If using Claude Code, the `homeclaw` plugin must be registered (`/plugin install homeclaw@homeclaw`). The `homeclaw-cli` binary must be in your PATH.
  561. >
  562. > Set up HomeClaw mapped webhooks with a dedicated HomeClaw agent. **Verify each step first -- skip any that are already configured.**
  563. >
  564. > **1. HomeClaw agent workspace:**
  565. > - Check if `homeclaw` agent exists: `openclaw agents list`
  566. > - If missing, install from the bundled app: `openclaw agents install homeclaw /Applications/HomeClaw.app/Contents/Resources/openclaw/agents/homeclaw`
  567. > - Copy agent docs (IDENTITY/SOUL/AGENTS/TOOLS.md) from the app bundle to the local agent dir if newer
  568. > - Configure agent: model `claude-sonnet-4`, restricted tools (memory, sessions/a2a, read/write only -- no exec, no browser, no external services)
  569. >
  570. > **2. OpenClaw gateway hooks config:**
  571. > - Check `~/.openclaw/openclaw.json` for a `hooks.mappings.homeclaw` entry
  572. > - If missing, add:
  573. > ```json
  574. > "hooks": {
  575. > "enabled": true,
  576. > "token": "${HOMECLAW_WEBHOOK_TOKEN}",
  577. > "mappings": {
  578. > "homeclaw": {
  579. > "agentId": "homeclaw",
  580. > "sessionKey": "hook:homeclaw",
  581. > "deliver": true,
  582. > "channel": "last",
  583. > "allowUnsafeExternalContent": true
  584. > }
  585. > }
  586. > }
  587. > ```
  588. > - Create a transform at `~/.openclaw/hooks/transforms/homeclaw-transform.js` to convert HomeClaw state-change payloads into agent messages
  589. > - Check `~/.openclaw/.env` for `HOMECLAW_WEBHOOK_TOKEN`. If missing, generate one: `openssl rand -base64 24 | tr '+/' '-_' | tr -d '='` and add it
  590. > - Remove any legacy `defaultSessionKey` entries that are no longer needed with dedicated mapping
  591. > - Restart gateway only if config changed: `openclaw gateway restart`
  592. >
  593. > **3. HomeClaw webhook config:**
  594. > - Check current config: `homeclaw-cli config --json`
  595. > - Verify: `webhook.enabled` is true, `webhook.url` is `http://127.0.0.1:18789`, `webhook.token` matches the `HOMECLAW_WEBHOOK_TOKEN` from step 2, and `webhook_endpoint` is `/hooks/homeclaw`
  596. > - Fix any mismatches via HomeClaw Settings UI or CLI
  597. > - If circuit breaker shows old failures, reset it
  598. >
  599. > **4. End-to-end test:**
  600. > - Run `homeclaw-cli config --webhook-test` -- expect HTTP 200
  601. > - Verify circuit state is `closed` and `last_success` is recent
  602. >
  603. > Report what was already configured, what was changed, and the test result.
  604. ### Manual Setup
  605. <details>
  606. <summary>Step-by-step without an AI assistant</summary>
  607. #### 1. Create the Agent Workspace
  608. The agent docs are bundled inside the HomeClaw app. Because the app bundle is read-only, you need a **local copy** for OpenClaw to use as the agent directory:
  609. ```bash
  610. # Create local agent dir with workspace
  611. mkdir -p ~/.openclaw/agents/homeclaw/{agent,workspace}
  612. # Copy agent docs from app bundle
  613. cp /Applications/HomeClaw.app/Contents/Resources/openclaw/agents/homeclaw/*.md \
  614. ~/.openclaw/agents/homeclaw/agent/
  615. # Register the agent
  616. openclaw agents add homeclaw \
  617. --agent-dir ~/.openclaw/agents/homeclaw/agent \
  618. --workspace ~/.openclaw/agents/homeclaw/workspace
  619. openclaw agents list # verify it appears
  620. ```
  621. > **Note:** `openclaw agents add` (not `install`) is the correct CLI command. The `--workspace` flag is required in non-interactive mode.
  622. #### 2. Configure OpenClaw
  623. Add the `hooks` block with `mappings` to `~/.openclaw/openclaw.json`:
  624. ```json
  625. "hooks": {
  626. "enabled": true,
  627. "token": "${HOMECLAW_WEBHOOK_TOKEN}",
  628. "mappings": {
  629. "homeclaw": {
  630. "agentId": "homeclaw",
  631. "sessionKey": "hook:homeclaw",
  632. "deliver": true,
  633. "channel": "last",
  634. "allowUnsafeExternalContent": true
  635. }
  636. }
  637. }
  638. ```
  639. The `mappings` entry routes all `/hooks/homeclaw` POSTs to the dedicated HomeClaw agent in a persistent `hook:homeclaw` session.
  640. **Create a transform** to convert HomeClaw payloads into agent messages. The hook mapping requires a `message` field in the payload -- without a transform, payloads with only `text` + `mode` will get a 400 error:
  641. ```bash
  642. mkdir -p ~/.openclaw/hooks/transforms
  643. cat > ~/.openclaw/hooks/transforms/homeclaw-transform.js << 'TRANSFORM'
  644. // Convert HomeClaw webhook payload {text, mode} into agent message format
  645. module.exports = function(payload) {
  646. return {
  647. message: payload.text || JSON.stringify(payload),
  648. mode: payload.mode || "next-heartbeat"
  649. };
  650. };
  651. TRANSFORM
  652. ```
  653. Then reference the transform in the mapping:
  654. ```json
  655. "homeclaw": {
  656. "agentId": "homeclaw",
  657. "sessionKey": "hook:homeclaw",
  658. "deliver": true,
  659. "channel": "last",
  660. "allowUnsafeExternalContent": true,
  661. "transform": "homeclaw-transform"
  662. }
  663. ```
  664. Generate a token and add it to `~/.openclaw/.env`:
  665. ```bash
  666. # Generate a secure token
  667. openssl rand -base64 24 | tr '+/' '-_' | tr -d '='
  668. # Add to .env
  669. echo 'HOMECLAW_WEBHOOK_TOKEN=<your-generated-token>' >> ~/.openclaw/.env
  670. ```
  671. Restart the gateway: `openclaw gateway restart`
  672. > **Warning:** The gateway rewrites `openclaw.json` on restart. Verify your mapping and transform entries survived by checking the file after restart. If a newly-added mapping is stripped, restart a second time -- there may be a race condition with first-time mappings.
  673. #### 3. Configure HomeClaw
  674. **Option A -- GUI:** Open Settings > Webhook. Toggle Enable, enter `http://127.0.0.1:18789` as the base URL, paste the same token from step 2.
  675. **Option B -- CLI** (note: the CLI updates the running daemon only -- it does not persist to `config.json`. Use the Settings UI or edit the config file directly for persistent changes):
  676. ```bash
  677. homeclaw-cli config --webhook-url "http://127.0.0.1:18789" \
  678. --webhook-token "your-token" \
  679. --webhook-enabled true
  680. ```
  681. #### 4. Test the Pipe
  682. ```bash
  683. homeclaw-cli config --webhook-test
  684. ```
  685. You should see an HTTP 200 response. If it fails, check the token matches and the OpenClaw gateway is running.
  686. > **Note:** Test events update `total_delivered` and `last_http_status` in the circuit breaker stats. After running `--webhook-test`, check `homeclaw-cli config --json` to confirm the values were updated.
  687. #### 5. Create Triggers
  688. In **Settings > Webhook**, check the accessories and scenes you want to fire webhooks. Only checked items generate events. Accessories with multiple characteristics (e.g., a sensor with both contact state and motion) show individual toggles so you can choose exactly which state changes fire webhooks. Battery-related characteristics are automatically excluded.
  689. > **Note:** Trigger creation is GUI-only. The CLI can list and manage existing triggers (`homeclaw-cli triggers list`, `triggers remove`), but new triggers must be created in the HomeClaw app's Settings > Webhook tab.
  690. #### 6. Test End-to-End
  691. ```bash
  692. # Verify HomeClaw is connected and webhook is healthy
  693. homeclaw-cli status
  694. # Toggle a light from the Home app, then check events
  695. homeclaw-cli events --since 5m
  696. # Check webhook delivery log
  697. homeclaw-cli webhook-log
  698. # Check HomeClaw delivery logs
  699. log show --predicate 'process == "HomeClaw" AND category == "webhook"' --last 5m --style compact
  700. ```
  701. </details>
  702. ### Circuit Breaker
  703. The webhook system includes a **tiered circuit breaker** that prevents runaway delivery failures from hammering a down endpoint, while ensuring critical events are never silently dropped.
  704. | State | Trigger | Behavior | Recovery |
  705. |-------|---------|----------|----------|
  706. | **Normal** | -- | All webhooks delivered | -- |
  707. | **Soft Open** | 5 consecutive failures | Non-critical paused | Auto-resumes after 5 minutes |
  708. | **Hard Open** | 3 soft trips without any success | All non-critical stopped | Reset button in Settings, `--webhook-reset` CLI, or toggle off/on |
  709. **Critical triggers** (`critical: true`) always attempt delivery regardless of circuit state.
  710. The circuit state is visible in:
  711. - **Menu bar** -- warning icon when paused or disabled
  712. - **Settings > Webhook** -- orange (paused) or red (disabled) banner with countdown
  713. - **CLI** -- `homeclaw-cli status` shows circuit state, dropped count, and recovery hint
  714. ### How Events Flow
  715. ```
  716. Home app / physical device / Siri
  717. |
  718. v
  719. HomeKit (HMAccessoryDelegate callback)
  720. |
  721. +-- Cache warmup? --> Update cache only (no logging, no webhooks)
  722. |
  723. +-- Battery event? --> Update cache only (silently dropped)
  724. |
  725. v
  726. HomeClaw event logger (writes to events.jsonl)
  727. |
  728. +-- Trigger matches? --> POST /hooks/homeclaw
  729. |
  730. +-- No trigger --> Logged to disk only (no webhook sent)
  731. v (trigger matched)
  732. OpenClaw gateway validates Bearer token
  733. |
  734. v
  735. hooks.mappings resolves "homeclaw"
  736. |
  737. v
  738. HomeClaw Agent (dedicated)
  739. +-- Classifies: CRITICAL / NOTABLE / AMBIENT
  740. +-- If notable/critical: a2a to main agent
  741. +-- If ambient: log to agent memory only
  742. ```
  743. ### Authentication
  744. Uses `Authorization: Bearer <token>` with idempotency headers (`X-Request-ID`, `X-Event-Timestamp`). See [SKILL.md](openclaw/skills/homekit/SKILL.md) for the full trigger fields reference, scenario cookbook, and troubleshooting.
  745. ## Device Filtering
  746. Use the [Devices tab](#devices) in Settings or the CLI to control which accessories are exposed:
  747. ```bash
  748. homeclaw-cli config --filter-mode allowlist
  749. homeclaw-cli config --allow-accessories "uuid1,uuid2,uuid3"
  750. homeclaw-cli config --list-devices # shows allowed/filtered status
  751. ```
  752. ## Building
  753. The build script uses XcodeGen to generate the Xcode project and `xcodebuild` to compile all targets (HomeClaw Catalyst app, macOSBridge bundle, homeclaw-cli tool):
  754. ```bash
  755. # Full release build + install to /Applications
  756. scripts/build.sh --release --install
  757. # Override team ID on the command line
  758. scripts/build.sh --release --install --team-id ABCDE12345
  759. # Debug build (faster)
  760. scripts/build.sh --debug
  761. # Clean build artifacts first
  762. scripts/build.sh --clean
  763. ```
  764. Your Apple Developer Team ID is required, provided via `.env.local`, `--team-id`, or the `HOMEKIT_TEAM_ID` environment variable.
  765. ### Archiving for App Store / TestFlight
  766. The release pipeline is `scripts/release.sh`, driving the App Store Connect CLI [`asc`](https://github.com/rorkai/App-Store-Connect-CLI). Full guide: [appstore/RELEASE.md](appstore/RELEASE.md).
  767. ```bash
  768. scripts/release.sh help
  769. scripts/release.sh status # ASC versions, builds, TestFlight groups (read-only)
  770. scripts/release.sh bump-build # Next build number -> Resources/Info.plist (commit + tag it)
  771. scripts/release.sh archive # Build a release .xcarchive (no upload)
  772. scripts/release.sh beta --dry-run # Archive + export .pkg + validate with Apple, no upload
  773. scripts/release.sh beta # ... then upload to TestFlight (Internal Testers)
  774. scripts/release.sh external # Send the build to External Testers + beta review
  775. scripts/release.sh release --dry-run # Push metadata + screenshots, submit for App Review
  776. # Tester notes default to appstore/metadata/en-US/release_notes.txt:
  777. TF_CHANGELOG="Bug fixes and improvements" scripts/release.sh beta
  778. # App Store screenshot pipeline (XCUITest-driven, demo mode, zero personal data):
  779. scripts/release.sh screenshots # Run HomeClawUITests in demo mode -> appstore/screenshots/en-US/
  780. scripts/release.sh frame # Frame them -> appstore/framed/en-US/
  781. scripts/release.sh upload-screenshots # Replace the Mac App Store screenshot set
  782. ```
  783. The screenshot pipeline uses **demo mode** — `HomeKitManager.isDemoMode` (gated on `--ui-test-demo` launch arg or `HOMECLAW_DEMO=1`) bypasses HomeKit and serves synthetic data from `Sources/homeclaw/HomeKit/DemoFixtures.swift`. Real HomeKit data is never read or shown. Attachments are extracted with `xcrun xcresulttool`, which ships with Xcode.
  784. Known follow-up: the menu-bar dropdown is `NSMenu` (AppKit), so it can't be auto-rendered via SwiftUI `ImageRenderer`. Capture it manually with `screencapture -x` of the running demo-mode app, or build a SwiftUI mockup of the dropdown.
  785. Auth uses an App Store Connect API key (`ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY_PATH`, or the `APP_STORE_CONNECT_API_*` names). Team ID comes from `.env.local` (`HOMEKIT_TEAM_ID`).
  786. To open the archive in Xcode Organizer instead of uploading:
  787. ```bash
  788. scripts/release.sh archive
  789. open '.asc/artifacts/HomeClaw.xcarchive'
  790. ```
  791. ### Version Bumping
  792. Version is derived from git tags at build time. To release a new version:
  793. ```bash
  794. scripts/bump-version.sh 0.2.0 # Updates source files + prints tag commands
  795. npm run build:mcp # Rebuild MCP server with new version
  796. git add -A && git commit -m "Bump version to 0.2.0"
  797. git tag -a v0.2.0 -m "HomeClaw v0.2.0"
  798. git push && git push origin v0.2.0
  799. ```
  800. ### Installing on Additional Macs
  801. Development-signed builds are tied to registered devices. To run HomeClaw on another Mac:
  802. 1. **Get the target Mac's Provisioning UDID** -- on that Mac, run:
  803. ```bash
  804. system_profiler SPHardwareDataType | grep "Provisioning UDID"
  805. ```
  806. 2. **Register the device** at [developer.apple.com/account/resources/devices/add](https://developer.apple.com/account/resources/devices/add):
  807. - **Platform**: macOS
  808. - **Device Name**: a descriptive name (e.g. "Living Room MacBook Air")
  809. - **Device ID**: the Provisioning UDID from step 1
  810. 3. **Rebuild** on your development machine (Xcode regenerates the provisioning profile to include the new device):
  811. ```bash
  812. scripts/build.sh --release --install --clean
  813. ```
  814. 4. **Copy** `/Applications/HomeClaw.app` to the target Mac (AirDrop, USB, network share, etc.)
  815. 5. **Grant HomeKit access** on first launch when prompted.
  816. > **Note:** The target Mac must be signed into iCloud with an account that has HomeKit home data. HomeKit homes are tied to iCloud accounts, not to the app.
  817. ### Why Development Signing?
  818. Apple restricts the `com.apple.developer.homekit` entitlement to **development signing** and **Mac App Store** distribution. It cannot be included in Developer ID provisioning profiles. A Developer ID build would pass Gatekeeper but have no HomeKit access (`HMHomeManager` returns zero homes). This is an [Apple platform restriction](https://developer.apple.com/forums/thread/699085), not a bug.
  819. ### Not Exposed by HomeKit
  820. Some devices that appear in the Home app never reach the public HomeKit API, so HomeClaw cannot see them regardless of configuration:
  821. - **HomePod and HomePod mini** — including the mini's built-in temperature and humidity sensors
  822. - **Apple TV**
  823. - The speaker component of accessories that embed one (an Ecobee's smart speaker, for example)
  824. These are absent from `HMHome.accessories` entirely. The Home app reaches them over a private media path that `HMHomeManager` does not expose. If you have HomePods assigned to a room and they don't show up in `homeclaw-cli list`, this is why — it isn't an accessory filter and it isn't a mapping gap.
  825. HomeClaw already maps speaker, television and microphone services, so if Apple ever surfaces these through the public API they will appear with no code change.
  826. ## Project Structure
  827. ```
  828. Sources/
  829. homeclaw/ Unified Catalyst app (Xcode target via XcodeGen)
  830. App/ UIApplicationDelegate entry point, scene delegates
  831. Bridge/ BridgeProtocols.swift (Mac2iOS, iOS2Mac)
  832. HomeKit/ HomeKitManager, SocketServer, CharacteristicMapper,
  833. AccessoryModel, DeviceMap, CharacteristicCache,
  834. HomeEventLogger, WebhookCircuitBreaker
  835. Views/ SettingsView, IntegrationsSettingsView
  836. Shared/ AppConfig, AppLogger, HomeClawConfig
  837. macOSBridge/ AppKit bundle (NSStatusItem menu bar)
  838. MacOSController.swift NSStatusItem + NSMenu via iOS2Mac protocol
  839. Info.plist NSPrincipalClass: MacOSController
  840. homeclaw-cli/ CLI tool (SPM executable + Xcode target)
  841. Commands/ list, get, set, search, scenes, get-scene, status, config, device-map,
  842. events, triggers, delete-scene, import-scene, assign-rooms
  843. SocketClient.swift Direct socket communication
  844. Resources/ Info.plist, entitlements, app icons
  845. scripts/
  846. build.sh Build, sign, and install
  847. bump-version.sh Update version across source files
  848. release.sh Release pipeline (asc): archive, TestFlight, App Store
  849. screenshots.sh Capture App Store screenshots via XCUITest
  850. frame_screenshots.sh Frame screenshots for the App Store
  851. appstore/
  852. metadata/ App Store listing (source of truth)
  853. screenshots/ Raw screenshots
  854. framed/ Framed screenshots (uploaded)
  855. RELEASE.md Release guide
  856. mcp-server/ Node.js stdio MCP server (wraps homeclaw-cli)
  857. openclaw/ OpenClaw plugin (HomeClaw)
  858. skills/homekit/ HomeKit skill with full characteristic reference
  859. App bundle layout (after build):
  860. Contents/MacOS/HomeClaw Catalyst app executable
  861. Contents/MacOS/homeclaw-cli Bundled CLI binary
  862. Contents/Resources/macOSBridge.bundle AppKit menu bar plugin
  863. Contents/Resources/mcp-server.js Node.js stdio MCP server
  864. Contents/Resources/openclaw/ Bundled OpenClaw plugin files
  865. ```
  866. ## Debugging
  867. The Node stdio MCP bridge checks the App Group socket at
  868. `~/Library/Group Containers/group.com.shahine.homeclaw/homeclaw.sock` on each
  869. request, then tries `/tmp/homeclaw.sock` if the preferred socket is missing or
  870. refuses the connection. Claude Desktop can start before HomeClaw; a later call
  871. will discover the running app without restarting Claude. Fallback happens only
  872. before connecting, so a command is never replayed after it has been sent. Socket
  873. files must belong to the current user; symlinks and non-socket files are rejected
  874. before any command is sent.
  875. If the bridge cannot connect, its error lists the attempted paths and connection
  876. errors. Launch HomeClaw, or restart it if it is already running. After installing
  877. an updated HomeClaw app, restart Claude Desktop to load the updated bundled MCP
  878. server. No socket symlink is needed.
  879. ```bash
  880. # Check if HomeClaw is running and HomeKit is ready
  881. echo '{"command":"status"}' | nc -U ~/Library/Group\ Containers/group.com.shahine.homeclaw/homeclaw.sock
  882. # Or via the CLI
  883. homeclaw-cli status
  884. # Verify HomeKit entitlement on installed app
  885. codesign -d --entitlements :- "/Applications/HomeClaw.app"
  886. # View HomeClaw logs
  887. log show --predicate 'process == "HomeClaw"' --last 10m --style compact
  888. # Check TCC (privacy) permissions
  889. sqlite3 ~/Library/Application\ Support/com.apple.TCC/TCC.db \
  890. "SELECT client, auth_value FROM access WHERE service = 'kTCCServiceWillow'"
  891. ```
  892. | Symptom | Cause | Fix |
  893. |---------|-------|-----|
  894. | 0 homes, `ready: false` | Missing HomeKit entitlement | Verify with `codesign -d --entitlements` |
  895. | All characteristic values `nil` | Accessory unreachable | Check device power and network |
  896. | "HomeKit Unavailable" in menu | iCloud not signed in | Sign into iCloud with HomeKit data |
  897. | CLI crashes with SIGTRAP | Missing bundle ID in sandbox | Rebuild with `CREATE_INFOPLIST_SECTION_IN_BINARY: YES` |
  898. ## Tech Stack
  899. - **Swift 6** with strict concurrency (`@MainActor`, `actor` isolation)
  900. - **Mac Catalyst** (UIKit) for HomeKit framework access
  901. - **AppKit** (via macOSBridge bundle) for native menu bar
  902. - **[Swift Argument Parser](https://github.com/apple/swift-argument-parser)** for CLI
  903. - **Node.js** + **[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)** for stdio MCP server
  904. - **XcodeGen** for Xcode project generation
  905. - **GCD** + Unix domain sockets for CLI/MCP communication
  906. ## FAQ
  907. ### `spctl --assess` says "rejected" -- is that a problem?
  908. No. `spctl` checks Gatekeeper, which only trusts Developer ID and App Store signing. HomeClaw uses **development signing** (required for HomeKit on macOS), so Gatekeeper will always reject it. This is expected and doesn't prevent the app from running -- AMFI handles development-signed apps separately via the embedded provisioning profile.
  909. ### Can I use a different Apple ID for HomeKit than my developer account?
  910. Yes. The two accounts serve completely different purposes:
  911. - **Apple Developer account** -- only matters at build time. Xcode uses it to create the provisioning profile and sign the code.
  912. - **iCloud account** (on the Mac running HomeClaw) -- determines which HomeKit homes appear. This is the account linked to your Home app data.
  913. These are independent. You can build HomeClaw with your developer account and run it on a Mac signed into a completely different iCloud account that has HomeKit homes. The HomeKit data follows the iCloud account, not the signing identity.
  914. ### When should I use `--clean`?
  915. Use `scripts/build.sh --clean` when:
  916. - Switching Apple Developer Team IDs
  917. - After major Xcode version updates
  918. - Build fails with signing or entitlement errors
  919. - You see code signature errors after rebuilding
  920. The `--clean` flag removes all build artifacts before building fresh.
  921. ### HomeKit shows 0 homes
  922. The app is running but can't see any HomeKit data. Check in order:
  923. 1. **iCloud signed in?** HomeKit data lives in iCloud. Open System Settings > Apple Account and verify.
  924. 2. **HomeKit entitlement present?** Run:
  925. ```bash
  926. codesign -d --entitlements :- "/Applications/HomeClaw.app"
  927. ```
  928. You should see `com.apple.developer.homekit` -> `true`.
  929. 3. **TCC permission granted?** On first launch, macOS asks for HomeKit access. If you denied it, re-grant in System Settings > Privacy & Security > HomeKit.
  930. 4. **Using Developer ID signing?** Only development signing supports the HomeKit entitlement. See [Why Development Signing?](#why-development-signing).
  931. ### How do I install on another Mac?
  932. Development-signed apps are tied to registered devices. See [Installing on Additional Macs](#installing-on-additional-macs) for the full walkthrough.
  933. ### How do I see what's happening?
  934. ```bash
  935. # HomeClaw app logs
  936. log show --predicate 'process == "HomeClaw"' --last 10m --style compact
  937. # Check HomeKit status directly over the socket
  938. homeclaw-cli status
  939. # Verify code signature and entitlements
  940. codesign -d --entitlements :- "/Applications/HomeClaw.app"
  941. ```
  942. ## License
  943. [MIT](LICENSE) -- Copyright (c) 2025 Omar Shahine

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.