homekit

HomeKit

Use homekit as the only HomeKit interface unless the user explicitly asks to leave this CLI. Start read-only, identify exact targets, then write only when the user has asked for the specific physical or structural change.

Progressive Disclosure

Do not memorize or duplicate the command schema. Ask the CLI for the level of detail you need:

homekit --help
homekit <group> --help
homekit <command> --schema --format json
homekit --llms

Use --format json for evidence you will parse or compare. Use --schema --format json before MCP/tool calls when argument names, output fields, or safety flags are uncertain.

Load References

Load only the reference that matches the user request:

• references/setup-and-troubleshooting.md: HomeClaw setup, readiness, HomeKit permission, logs, MCP install.
• references/inspection-workflows.md: homes, rooms, accessories, scenes, automations, zones, event logs, device-map, and anomaly investigation.
• references/write-workflows.md: accessory control, room/zone/scene/automation mutations, exact-id writes, verification, and audit reporting.
• references/command-groups.md: concise command group map and implementation caveats.

Use scripts/homekit-readiness.sh when you need a deterministic local setup/readiness check.

Operating Rules

• Treat locks, garage doors, gates, doors, windows, covers, security systems, cameras, doorbells, occupancy, presence, scenes, and automations as safety-critical.
• Never control a device just to test connectivity.
• Never use --allow-actuation unless the user asked for the exact physical state change.
• Never use --allow-mutation unless the user asked for the exact HomeKit structural change.
• Never wildcard writes. Resolve names to exact IDs first, then use those exact IDs.
• If multiple accessories, scenes, rooms, zones, or automations match, show candidates and ask the user to choose.
• After any accepted write, report the command family, target name/id, requested value/change, verification result, and returned auditId when present.