/homeclaw

description: |
  Control HomeKit smart home accessories via HomeClaw MCP tools.
  Also includes reference data for accessory categories, characteristics, and value formats.
  This skill should be used when the user wants to:
  - Turn lights on or off, set brightness, or change color temperature
  - Lock or unlock doors
  - Set thermostat temperature or HVAC mode
  - Run a HomeKit scene like "Good Morning" or "Movie Time"
  - Check which devices are on, off, or unreachable
  - List accessories in a room or search by name
  - Check HomeClaw status or configure default home
  - Look up characteristic names, value types, ranges, or enum mappings
  Example triggers: "turn on the kitchen lights", "lock all doors",
  "set the thermostat to 72", "run the goodnight scene", "what lights are on",
  "list devices in the living room", "is HomeClaw running",
  "what characteristics does a thermostat have", "what are the lock state values"

HomeKit Smart Home Control

HomeClaw exposes Apple HomeKit accessories via MCP tools. Use the `homekit_*` tools as the interface for all HomeKit operations.

MCP Tools

The plugin registers 8 MCP tools.

| Tool | Description | |------|-------------| | `homekit_status` | Check bridge connectivity, home count, accessory count | | `homekit_accessories` | List, get details, search, or control accessories | | `homekit_rooms` | List rooms and their accessories | | `homekit_scenes` | List, get details of, trigger, import, or delete scenes | | `homekit_device_map` | Get LLM-optimized device map with semantic types, aliases, and zone hierarchy | | `homekit_events` | Query recent HomeKit events (characteristic changes, scene triggers, control actions) | | `homekit_automations` | Manage automations: list, create (inline actions or scene), delete, enable/disable | | `homekit_webhook` | Manage webhook configuration: setup, test, reset circuit breaker, status | | `homekit_config` | View or update bridge configuration |

homekit_device_map

Returns a complete LLM-optimized device map organized by home/zone/room hierarchy. Each device includes:

| Field | Description | |-------|-------------| | `semantic_type` | Functional type: `lighting`, `climate`, `security`, `door_lock`, `window_covering`, `sensor`, `power`, `media`, `network`, `other` | | `display_name` | Room-prefixed name for disambiguation (only when duplicates exist) | | `aliases` | Auto-generated search terms like "kitchen light", "overhead in kitchen" | | `controllable` | List of writable characteristics (e.g., `["power", "brightness"]`) | | `state_summary` | One-line state: "on 75%", "72°F heating", "locked", "off", "unreachable" | | `manufacturer` | Device manufacturer | | `description` | Natural-language summary: "Lutron lighting (power, brightness), on 75%" |

**Use this tool first** when you need to understand the device landscape before controlling devices. It resolves name collisions and identifies switches that actually control lights.

Semantic Type Reference

| Semantic Type | Maps From | Key Distinction | |--------------|-----------|-----------------| | `lighting` | lightbulbs | Devices with brightness/color control | | `climate` | thermostats, fans, air purifiers | | | `security` | doors, garage doors, cameras, doorbells, security systems | | | `door_lock` | locks | | | `window_covering` | windows, blinds, shades | | | `sensor` | motion, contact, temperature, humidity sensors | | | `power` | outlets, switches, programmable switches | In-wall switches get light aliases for search | | `media` | speakers, televisions | |

homekit_accessories

The main workhorse tool. Supports 4 actions via the `action` parameter:

| Action | Required Params | Description | |--------|----------------|-------------| | `list` | — | List all accessories. Optional: `room`. Returns enriched results with `semantic_type`, `display_name`, `manufacturer`, `zone`. | | `get` | `accessory_id` | Get full detail with all characteristics | | `search` | `query` | Search by name, room, category, semantic type, manufacturer, or aliases (e.g., "kitchen light" matches switches with lightbulb services). Optional: `category` | | `control` | `accessory_id`, `characteristic`, `value` | Set a characteristic value |

homekit_scenes

| Action | Required Params | Description | |--------|----------------|-------------| | `list` | — | List all scenes with name, type, and action count | | `get` | `scene_id` | Get full scene detail including all actions (accessory, room, characteristic, target value) | | `trigger` | `scene_id` | Execute a scene by name or UUID |

homekit_events

| Param | Required | Description | |-------|----------|-------------| | `since` | No | Duration shorthand (`1h`, `30m`, `2d`) or ISO 8601 timestamp | | `type` | No | Filter: `characteristic_change`, `scene_triggered`, `accessory_controlled`, `homes_updated` | | `limit` | No | Max events to return (default: 50) |

homekit_automations

| Action | Required Params | Description | |--------|----------------|-------------| | `list` | — | List all automations with event summaries and linked scenes | | `get` | `id` | Detail view with events, action sets, and button info | | `create` | `name`, `accessory_id`, plus `actions` or `scene_id` | Create a button-press automation (see below) | | `delete` | `id` | Delete an automation | | `enable` | `id` | Enable a disabled automation | | `disable` | `id` | Disable an automation without deleting |

**Create parameters:**

| Param | Required | Description | |-------|----------|-------------| | `name` | Yes | Human-readable automation name | | `accessory_id` | Yes | Button accessory UUID or name | | `actions` | One of | Inline actions array (default, no visible scene). Each entry: `{accessory, property, value}` | | `scene_id` | One of | Existing scene UUID or name to trigger | | `press_type` | No | 0=single (default), 1=double, 2=long press | | `service_index` | No | Button index for multi-button accessories (1 or 2) |