Stop Fighting HomeKit's Closed API! HomeClaw Exposes Everything

What if your AI assistant could actually control your entire smart home? Not just Alexa's walled garden. Not just Google's data harvest. I'm talking about Apple HomeKit—the most secure, most private, and most infuriatingly closed smart home platform on the planet.

Here's the dirty secret Apple doesn't want you to know: HomeKit has no public API. None. Zero. Zilch. Want to script your lights from the terminal? Impossible. Want Claude to lock your doors? Forget it. Want to build automations that go beyond the Home app's toy-level shortcuts? Apple says "tough luck."

Developers have been stuck in this prison for years. We've resorted to brittle workarounds—HomeBridge hacks, Home Assistant bridges, reverse-engineered protocols that break every iOS update. It's exhausting. It's unreliable. And it's completely unnecessary now.

Enter HomeClaw—the tool that's making waves across GitHub, Reddit, and every developer Discord I'm in. Built by Omar Shahine, this lightweight macOS menu bar app doesn't just crack open HomeKit's black box. It obliterates the barrier entirely, exposing your lights, locks, thermostats, and scenes through a clean CLI, a stdio MCP server, and native plugins for Claude Desktop, Claude Code, and OpenClaw.

The best part? It's on the Mac App Store. Fully signed. Fully notarized. No developer account gymnastics required for most users.

If you've ever yelled at your Home app while wishing you could just curl your lights off, this article is your salvation. Let's dive into why HomeClaw is the HomeKit bridge developers have been begging for—and how to wield it like a pro.

What is HomeClaw?

HomeClaw is a Mac Catalyst application that acts as a secure bridge between Apple's proprietary HomeKit framework and the outside world. Created by Omar Shahine (a veteran engineer with deep Apple platform expertise), it solves a problem that has plagued the HomeKit ecosystem since day one: Apple's HMHomeManager requires a UIKit/Catalyst app with the restricted com.apple.developer.homekit entitlement.

No command-line tool can get this entitlement. No background daemon. No Docker container. Only a signed, entitled macOS application can talk to HomeKit—and even then, Apple restricts it to development signing or Mac App Store distribution.

Shahine's genius move? He built the entire stack as a single Catalyst process. The app itself contains the HomeKit manager, a Unix socket server for CLI/MCP clients, and an AppKit bridge bundle for the menu bar. This unified architecture means:

• Direct HomeKit access with no inter-process communication overhead
• Single signing identity for clean App Store submission
• Zero configuration for end users

The project exploded in popularity because it arrives at a perfect storm: AI assistants are everywhere, the Model Context Protocol (MCP) is becoming the standard for tool-augmented LLMs, and developers are desperate to integrate their physical environments with their digital workflows.

HomeClaw isn't just a utility. It's a statement that smart homes deserve to be as hackable as the rest of our stacks.

Key Features That Make HomeClaw Insane

HomeClaw packs a staggering amount of capability into a deceptively simple menu bar icon. Here's what separates it from every other HomeKit bridge attempt:

Native MCP Server Integration

The stdio MCP server wraps homeclaw-cli and exposes 10 powerful tools to any MCP-compatible client. This isn't a janky HTTP API—it's the Model Context Protocol, the emerging standard that lets Claude, Cursor, and other AI assistants discover and invoke tools dynamically. The server requires zero authentication because security is handled at the Unix socket level.

Full-Spectrum Accessory Control

Lights with brightness, hue, saturation, and color temperature. Thermostats with HVAC modes and humidity. Locks, garage doors, fans with speed/direction/swing, window coverings, switches, outlets, motion sensors, contact sensors, doorbells, programmable switches—HomeClaw handles the complete HomeKit taxonomy, not just the easy stuff.

Scene Engine with Import/Export

Create scenes from JSON, trigger existing ones, inspect their full action sets, bulk-assign accessories to rooms, and preview changes with --dry-run before committing. This is infrastructure-as-code for your living room.

Automation Programming

HomeClaw can program physical buttons (like Aqara switches) with single, double, and long-press triggers. Link them to scenes or inline device actions. It's the missing HomeKit automation layer that Apple's own app hides behind private APIs.

Event Logging & Webhooks

Every characteristic change, scene trigger, and control action gets logged to a rotating JSONL file. Configure webhooks to push events to OpenClaw or any HTTP endpoint, with circuit breaker protection against cascade failures.

Interactive Terminal UI

Launch homeclaw-cli ui for a full-screen, keyboard-driven browser of your home. Navigate rooms, see live state with color-coded indicators, and toggle devices with Enter. It works over SSH. It respects demo mode for screenshots. It's built on SwiftTUI and feels like a hacker's dream.

Intelligent Device Filtering

Expose all accessories or maintain a strict allowlist. Per-device toggles with category icons, room grouping, search, and bulk selection. Your AI assistant only sees what you want it to see.

Real-World Use Cases Where HomeClaw Dominates

1. AI-Powered Natural Language Home Control

Stop memorizing Siri's rigid command structure. With Claude Desktop or Claude Code, you simply talk:

"Turn on the kitchen lights and set them to 50% brightness" "Lock all the doors and arm the security system" "What's the thermostat set to? Is anyone home?" "Run the movie time scene and dim the hallway to 10%"

The MCP protocol means Claude discovers available tools automatically. No hardcoded intents. No training phrases. Just natural conversation with your physical environment.

2. Terminal-Driven DevOps for Your Home

You're already in the terminal all day. Why context-switch to a phone app?

# Morning routine: lights on, temperature up, coffee machine powered
homeclaw-cli set "Kitchen Light" brightness 100
homeclaw-cli set "Thermostat" target_temperature 72
homeclaw-cli set "Coffee Maker" power_state 1

# Check before leaving
homeclaw-cli list --json | jq '.[] | select(.room == "Entryway")'

Pipe it to jq. Cron it. Integrate it with your existing dotfiles and automation scripts. Your home becomes just another service in your infrastructure.

3. Cross-Platform Automation Beyond HomeKit Shortcuts

Apple's Shortcuts app is cute for simple timers. It's useless for complex logic. With HomeClaw's webhook system, you can:

• Trigger scenes from GitHub Actions when deployments succeed
• Log door unlock events to your SIEM
• Build custom dashboards with Grafana consuming the JSONL event log
• Create multi-step automations that conditionally branch based on time, weather, or external APIs

4. Remote Management & SSH Access

SSH into your home Mac from anywhere and run the TUI:

ssh home-mac.local
homeclaw-cli ui

Navigate with arrow keys, toggle with Enter, quit with Ctrl-D. No VNC. No screen sharing. Just a lightweight terminal interface that works over any connection. Perfect for checking if you left the lights on after that redeye flight.

Step-by-Step Installation & Setup Guide

Mac App Store (Recommended for 99% of Users)

This is the zero-friction path. Apple handles all the signing complexity.

# Click the badge or visit directly
open "https://apps.apple.com/us/app/homeclaw/id6759682551?mt=12"

1. Install from the Mac App Store
2. Launch HomeClaw — grant HomeKit access when macOS prompts
3. Menu bar icon appears — click to see connected homes

That's it. App Store builds are fully signed and notarized. HomeKit works immediately with no developer account.

TestFlight Beta (Early Access)

Want features before they ship?

open "https://testflight.apple.com/join/zjSnz8eK"

Install from TestFlight, launch, grant HomeKit access. Identical signing to App Store builds.

Build from Source (Developers & Customizers)

Only needed if you want to modify code or can't use the App Store.

Prerequisites:

• macOS 26 (Tahoe) or later
• Xcode 26+ with Swift 6.2
• XcodeGen: brew install xcodegen
• Node.js 20+
• Apple Developer account with HomeKit capability enabled

Critical: Apple restricts com.apple.developer.homekit to development signing and App Store distribution. Every Mac you run on must be registered as a development device in your Apple Developer portal. This is Apple's rule, not HomeClaw's.

# Clone the repository
git clone https://github.com/omarshahine/HomeClaw.git
cd HomeClaw

# Configure your Apple Developer Team ID
echo "HOMEKIT_TEAM_ID=YOUR_TEAM_ID" > .env.local

# Install Node.js dependencies
npm install

# Build and install to /Applications
scripts/build.sh --release --install

Find your Team ID at developer.apple.com/account under Membership Details.

Launch with open "/Applications/HomeClaw.app" and grant HomeKit access on first run.

Post-Installation: AI Integrations

REAL Code Examples from HomeClaw

These are actual commands and configurations from the repository, explained with production-ready context.

Example 1: MCP Server Configuration for Claude Desktop

The heart of AI integration. This JSON config tells Claude Desktop how to spawn the HomeClaw MCP server:

{
  "mcpServers": {
    "homeclaw": {
      "command": "node",
      "args": ["/Applications/HomeClaw.app/Contents/Resources/mcp-server.js"]
    }
  }
}

What's happening here? The mcp-server.js file is bundled inside the app itself at a known path. Claude Desktop spawns this Node.js process, which communicates via stdio using the Model Context Protocol. The server wraps homeclaw-cli, translating MCP tool calls into socket commands to the running HomeClaw app.

Key insight: No authentication needed in the config because the Unix domain socket is protected by macOS filesystem permissions. If you can execute the binary, you're already authorized. The --install flag in scripts/build.sh ensures proper permissions.

Example 2: Comprehensive CLI Control Patterns

HomeClaw's CLI is where power users live. Here's a progression from basic to advanced:

# ── BASIC: List and search ──
homeclaw-cli list                           # All accessories
homeclaw-cli list --room "Kitchen"          # Filter by room
homeclaw-cli list --category thermostat     # Filter by type
homeclaw-cli search "bedroom" --category lightbulb  # Semantic search

# ── CONTROL: Set device state ──
homeclaw-cli set "Living Room Light" brightness 75
homeclaw-cli set "Front Door Lock" lock_target_state locked
homeclaw-cli set "Thermostat" target_temperature 72

# ── ADVANCED: Disambiguate bridged devices ──
# When a characteristic exists on multiple services (common with TVs),
# specify the exact service UUID
homeclaw-cli set "TV" active 0 \
  --service-type 000000D8-0000-1000-8000-0026BB765291

# ── SCENES: Trigger and inspect ──
homeclaw-cli trigger "Good Night"
homeclaw-cli get-scene "Good Night" --json  # Full action detail for scripting

# ── SAFE MUTATIONS: Preview before committing ──
homeclaw-cli set "Front Door" lock_target_state locked --dry-run
homeclaw-cli delete-scene "Movie Night" --dry-run

The --service-type flag is crucial for bridged accessories. Many Zigbee/Z-Wave bridges expose multiple services under one accessory. Without disambiguation, HomeClaw can't know which "active" characteristic you mean—the TV's power or the volume control's. The UUID format follows HomeKit's standard 128-bit service type identifiers.

Example 3: Scene Import with JSON Infrastructure-as-Code

Define reproducible scenes in version-controlled JSON:

{
  "name": "Movie Night",
  "actions": [
    {"accessory": "Living Room Light", "room": "Living Room", "property": "brightness", "value": "30%"},
    {"accessory": "TV Backlight", "room": "Living Room", "property": "power_state", "value": "ON"},
    {"accessory": "Overhead", "room": "Living Room", "property": "power_state", "value": "OFF"}
  ]
}

Then apply with safety:

# Preview what would change
homeclaw-cli import-scene scene.json --dry-run

# Actually create the scene
homeclaw-cli import-scene scene.json

Why this matters: You can commit scene.json to git, code-review lighting changes, and deploy them through CI/CD. The room field provides disambiguation when accessories share names across rooms. The --dry-run flag validates all accessory names and properties before touching HomeKit, preventing partial scene creation.

Example 4: Automation Creation with Inline Actions

Program physical buttons with complex multi-device triggers:

# Scene-based: simple button-to-scene mapping
homeclaw-cli automations create --name "Gym Lights" \
  --accessory "Gym Button" --scene "Gym On" --press single

# Inline actions: direct device control with UUIDs for precision
homeclaw-cli automations create --name "Sarah's Room Open" \
  --accessory "Office Button" \
  --action "BE21C139-413A-50F9-B97F-B9BDA06302A8:power:true" \
  --action "52195C6F-6FAA-5E52-AA56-840A6605EEAA:target_position:100" \
  --press single --service-index 1

Critical nuance: The --service-index targets specific buttons on multi-button switches in "fast mode." Some Aqara switches support either fast mode (2 buttons, instant response) or multi-event mode (1 button with single/double/long press, ~300ms delay). HomeClaw handles both but requires explicit targeting.

UUID vs. name: Inline actions accept UUIDs to avoid name collisions. A ceiling fan might expose both a light and fan service with the same accessory name—UUIDs eliminate ambiguity. The format is <UUID>:<characteristic>:<value>.

Example 5: Webhook Configuration for OpenClaw Integration

Push HomeKit events to your AI agent infrastructure:

# Configure webhook endpoint
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

# Verify connectivity
homeclaw-cli config --webhook-test

# Create targeted triggers (GUI for creation, CLI for management)
homeclaw-cli triggers add --label "Front Door" --accessory-id "<uuid>"
homeclaw-cli triggers add --label "Mailbox Open" --accessory-id "<uuid>" \
  --characteristic contact_state

The circuit breaker protects your gateway. After 5 consecutive failures, non-critical webhooks pause for 5 minutes. After 3 soft trips without success, all non-critical delivery stops until manually reset. Critical triggers (leak sensors, security devices marked critical: true) always attempt delivery.

Advanced Usage & Best Practices

Filter Before You Expose

Use allowlist mode for AI assistant integrations. You don't want Claude accidentally controlling your garage door because it misheard "kitchen lights."

homeclaw-cli config --filter-mode allowlist
homeclaw-cli config --list-devices  # Review what's exposed

Leverage JSON Output for Pipelines

Every read command supports --json or auto-detects non-TTY output:

homeclaw-cli list --json | jq '.[] | select(.category == "lightbulb" and .power_state == 1) | .name'
homeclaw-cli events --since 1h --json | jq 'group_by(.type) | map({type: .[0].type, count: length})'

SSH with TUI for Remote Management

The TUI works over SSH because it uses SwiftTUI, not AppKit:

ssh -t home-mac.local "homeclaw-cli ui"

The -t flag allocates a pseudo-TTY, required for interactive terminal applications.

Event Log as Audit Trail

The rotating JSONL log at ~/Library/Application Support/HomeClaw/events.jsonl is perfect for compliance and debugging. Configure rotation to prevent disk bloat:

# Check current log stats
homeclaw-cli events --limit 1  # Triggers status display

Demo Mode for Documentation

Launch with --ui-test-demo or HOMECLAW_DEMO=1 for synthetic data. Essential for screenshots, tutorials, and CI testing without exposing real home data.

Comparison with Alternatives

HomeBridge and Home Assistant are excellent for bringing non-HomeKit devices into HomeKit. HomeClaw is the inverse: it exposes HomeKit outward to developers, AI assistants, and automation pipelines. They're complementary, not competitive.

FAQ: What Developers Ask Most

Why does HomeClaw need development signing for source builds?

Apple restricts the com.apple.developer.homekit entitlement to development signing and App Store distribution. Developer ID (notarized) builds cannot include it. This is Apple's platform restriction, not HomeClaw's limitation. Use the Mac App Store build to avoid this entirely.

Can I run HomeClaw on multiple Macs?

App Store builds: yes, on any Mac signed into the same Apple ID. Source builds: each Mac must be registered as a development device in your Apple Developer portal, then rebuilt with the updated provisioning profile.

Does HomeClaw work with non-Apple HomeKit accessories?

Yes—anything that appears in Apple's Home app works with HomeClaw. This includes Philips Hue, Eve, Aqara, Nanoleaf, and hundreds of other brands that support HomeKit natively or via Matter.

Is my HomeKit data sent to any cloud service?

No. All communication stays local: Unix domain sockets between components, direct HomeKit framework calls, and optional webhooks only to endpoints you configure. The Mac App Store build never phones home.

What happens if the HomeClaw app crashes?

The CLI and MCP server detect socket disconnection and report clear errors. Restart the app and connections resume automatically. No state is lost—HomeKit itself remains the source of truth.

Can I use HomeClaw with Cursor, Windsurf, or other AI editors?

Any MCP-compatible client works. Configure the same mcpServers.homeclaw block in their respective config files. The stdio server is editor-agnostic.

How do I contribute or report bugs?

The repository is at github.com/omarshahine/HomeClaw. Issues, PRs, and feature requests are welcome. The codebase uses Swift 6 with strict concurrency, XcodeGen for project generation, and fastlane for release automation.

Conclusion: Your HomeKit Prison Break Starts Now

Apple built a beautiful, secure smart home ecosystem—and then locked the door and threw away the key. For years, developers accepted this as immutable reality. We hacked around it. We compromised. We settled for less.

HomeClaw proves we never had to.

By embracing Mac Catalyst's unique position as the only sanctioned path to HomeKit, Omar Shahine didn't just build a bridge. He built a highway—multi-lane, well-lit, with clear signage for CLI users, AI assistant integrators, and automation engineers alike. The MCP server integration is particularly forward-thinking, positioning HomeClaw at the center of the emerging AI-agent ecosystem rather than as a retrofitted afterthought.

Whether you're whispering to Claude to dim the lights, SSHing into your home server to check the thermostat, or building webhook-driven automations that make your house genuinely intelligent, HomeClaw delivers.

Stop fighting HomeKit's closed API. Start controlling it.

📥 Download HomeClaw from the Mac App Store

⭐ Star the repository on GitHub

🧪 Join the TestFlight beta for early access to new features

Your smart home was never meant to be a walled garden. With HomeClaw, it finally isn't.