Install Node.js dependencies

npm install

Install

Marketing site with screenshots and full pitch: homeclaw.omarknows.app.

After installing

Set up your AI integrations:

• Claude Desktop -- one-click install from Settings > Integrations, or add the MCP server config manually
• Claude Code -- install the plugin from GitHub
• 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: 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

```bash 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

Build everything and install

scripts/build.sh --release --install ```

Find your Team ID at 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? for details.

</details>

Installing the Plugin

Install from a local clone or directly from GitHub.

From a local clone:

```bash

Inside Claude Code, register the marketplace and install

/plugin marketplace add ~/GitHub/HomeClaw /plugin install homeclaw@homeclaw

**From GitHub (no local clone needed):**

Install the plugin

/plugin install homeclaw@homeclaw ```

After installing, restart Claude Code. Then just ask:

"Turn on the kitchen lights and set them to 50% brightness" "Lock all the doors" "What's the thermostat set to?" "Run the movie time scene" "Which lights are on in the living room?"

Same-Mac Install (Recommended)

If HomeClaw and OpenClaw run on the same Mac, use the one-click installer:

1. Open Settings > Integrations and click Install in the OpenClaw section.

This handles all four steps automatically: installs the plugin, enables it, symlinks homeclaw-cli into your PATH, and restarts the gateway.

Or from the terminal:

```bash

1. Install the plugin from the bundled files

openclaw plugins install "/Applications/HomeClaw.app/Contents/Resources/openclaw/" openclaw plugins enable homeclaw

Install the plugin

openclaw plugins install ~/GitHub/HomeClaw/openclaw openclaw plugins enable homeclaw

Setup with AI Assistant

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:

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. Set up HomeClaw mapped webhooks with a dedicated HomeClaw agent. Verify each step first -- skip any that are already configured. 1. HomeClaw agent workspace: - Check if homeclaw agent exists: openclaw agents list - If missing, install from the bundled app: openclaw agents install homeclaw /Applications/HomeClaw.app/Contents/Resources/openclaw/agents/homeclaw - Copy agent docs (IDENTITY/SOUL/AGENTS/TOOLS.md) from the app bundle to the local agent dir if newer - Configure agent: model claude-sonnet-4, restricted tools (memory, sessions/a2a, read/write only -- no exec, no browser, no external services) 2. OpenClaw gateway hooks config: - Check ~/.openclaw/openclaw.json for a hooks.mappings.homeclaw entry - If missing, add:

> "hooks": {
>   "enabled": true,
>   "token": "${HOMECLAW_WEBHOOK_TOKEN}",
>   "mappings": {
>     "homeclaw": {
>       "agentId": "homeclaw",
>       "sessionKey": "hook:homeclaw",
>       "deliver": true,
>       "channel": "last",
>       "allowUnsafeExternalContent": true
>     }
>   }
> }
> 

- Create a transform at ~/.openclaw/hooks/transforms/homeclaw-transform.js to convert HomeClaw state-change payloads into agent messages - Check ~/.openclaw/.env for HOMECLAW_WEBHOOK_TOKEN. If missing, generate one: openssl rand -base64 24 | tr '+/' '-_' | tr -d '=' and add it - Remove any legacy defaultSessionKey entries that are no longer needed with dedicated mapping - Restart gateway only if config changed: openclaw gateway restart 3. HomeClaw webhook config: - Check current config: homeclaw-cli config --json - 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 - Fix any mismatches via HomeClaw Settings UI or CLI - If circuit breaker shows old failures, reset it 4. End-to-end test: - Run homeclaw-cli config --webhook-test -- expect HTTP 200 - Verify circuit state is closed and last_success is recent Report what was already configured, what was changed, and the test result.

Manual Setup

<details> <summary>Step-by-step without an AI assistant</summary>

1. Create the Agent Workspace

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:

```bash

Building

The build script uses XcodeGen to generate the Xcode project and xcodebuild to compile all targets (HomeClaw Catalyst app, macOSBridge bundle, homeclaw-cli tool):

```bash

Full release build + install to /Applications

scripts/build.sh --release --install

Debug build (faster)

scripts/build.sh --debug

Clean build artifacts first

scripts/build.sh --clean ```

Your Apple Developer Team ID is required, provided via .env.local, --team-id, or the HOMEKIT_TEAM_ID environment variable.

Installing on Additional Macs

Development-signed builds are tied to registered devices. To run HomeClaw on another Mac:

1. Get the target Mac's Provisioning UDID -- on that Mac, run:

   system_profiler SPHardwareDataType | grep "Provisioning UDID"
   

2. Register the device at developer.apple.com/account/resources/devices/add: - Platform: macOS - Device Name: a descriptive name (e.g. "Living Room MacBook Air") - Device ID: the Provisioning UDID from step 1

3. Rebuild on your development machine (Xcode regenerates the provisioning profile to include the new device):

   scripts/build.sh --release --install --clean
   

1. Copy /Applications/HomeClaw.app to the target Mac (AirDrop, USB, network share, etc.)

1. Grant HomeKit access on first launch when prompted.

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.

Verify HomeKit entitlement on installed app

codesign -d --entitlements :- "/Applications/HomeClaw.app"

How do I install on another Mac?

Development-signed apps are tied to registered devices. See Installing on Additional Macs for the full walkthrough.

Screenshots

<p align="center"> <img src="docs/images/framed-settings.png" width="700" alt="Settings — HomeKit homes and accessories overview"> <br><em>Settings — every preference in one place</em> </p>

<p align="center"> <img src="docs/images/framed-cli-list.png" width="700" alt="CLI — list every accessory in one command"> <br><em>CLI — every accessory, one command away</em> </p>

<p align="center"> <img src="docs/images/framed-tui.png" width="700" alt="Terminal UI — accessory tree with live status"> <br><em>Terminal UI — for power users</em> </p>

Status and configuration

homeclaw-cli status homeclaw-cli config --default-home "Main House" homeclaw-cli config --filter-mode allowlist homeclaw-cli config --list-devices

Webhook configuration

homeclaw-cli config --webhook-url "http://127.0.0.1:18789" homeclaw-cli config --webhook-token "your-secret-token" homeclaw-cli config --webhook-enabled true homeclaw-cli config --webhook-test # Send test event, show HTTP response homeclaw-cli config --webhook-reset # Reset circuit breaker without toggling

Auto-JSON: all commands output JSON when piped or when env var is set

homeclaw-cli status | jq . # Auto-detects non-TTY OUTPUT_FORMAT=json homeclaw-cli list # Force JSON via env var ```

Settings

Five configuration tabs accessible from the menu bar:

Configuration

Open Settings > Event Log to configure:

• Enable/disable event logging
• Max file size (10-500 MB) -- when the log reaches this size, it's rotated
• Rotated backups (0-10) -- how many old log files to keep before deleting the oldest
• Purge -- delete all event log files
• Show in Finder -- reveal the log directory

Or configure via CLI:

homeclaw-cli events                         # Show recent events
homeclaw-cli events --since 1h              # Last hour
homeclaw-cli events --type characteristic_change  # Filter by type
homeclaw-cli events --limit 200 --json      # JSON output

Event types: characteristic_change, scene_triggered, accessory_controlled, homes_updated

The --since flag accepts ISO 8601 timestamps or duration shorthand: 1h, 30m, 2d.

Add to .env

echo 'HOMECLAW_WEBHOOK_TOKEN=<your-generated-token>' >> ~/.openclaw/.env

Restart the gateway: `openclaw gateway restart`

> **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.

#### 3. Configure HomeClaw

**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.

**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):

#### 4. Test the Pipe

You should see an HTTP 200 response. If it fails, check the token matches and the OpenClaw gateway is running.

> **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.

#### 5. Create Triggers

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.

> **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.

#### 6. Test End-to-End

2. Symlink the CLI into PATH (the skill calls homeclaw-cli by name)

Symlink the CLI into PATH

ln -sf /path/to/homeclaw-cli /opt/homebrew/bin/homeclaw-cli

3. Restart the gateway to load the plugin

openclaw gateway restart ```

Integrations

Install and manage connections to AI assistants. The app detects existing configurations and guides you through setup:

• Claude Desktop -- one-click install of the bundled stdio MCP server (requires Node.js)
• Claude Code -- detects the installed plugin (homeclaw@homeclaw)
• OpenClaw -- detects plugin configuration on the remote gateway and provides setup instructions

<p align="center"><img src="docs/images/settings-integrations.png" width="500" alt="Integrations settings tab"></p>

App Store screenshot pipeline (XCUITest-driven, demo mode, zero personal data):

fastlane screenshots # Run HomeClawUITests in demo mode, extract PNGs to fastlane/screenshots/en-US/ fastlane upload_screenshots # Push screenshots to App Store Connect

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. Requires `xcparse` (`brew install chargepoint/xcparse/xcparse`).

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.

Auth uses an App Store Connect API key from `~/.secrets.env` (`ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_KEY_PATH`). Team ID comes from `.env.local` (`HOMEKIT_TEAM_ID`).

To open the archive in Xcode Organizer instead of uploading:

FAQ