HomeKit Extractor: Export Your Entire HomeKit Setup (Including Shortcut Automations) to Home Assistant

Community Guides
,
1

The Problem

If you’ve got a complex HomeKit setup and want to migrate to Home Assistant, you hit a wall immediately:

  1. Apple hides automation logic. The HMShortcutAction API returns only a name — nothing about the conditional logic, device actions, or workflow inside. Controllers for HomeKit, Eve, all the third-party apps — they all see the same opaque object.
  2. No export feature exists. Apple provides zero way to export automations from the Home app.
  3. Manual migration is brutal. You’re rewriting automations by hand, scene by scene, automation by automation.

This is especially painful if you’ve built complex “Convert to Shortcut” automations with if/then/else logic — that data just looks like a wall you can’t read.

The Solution

homekit-extractor bypasses Apple’s API limitations by combining two extraction methods:

Method 1: Mac Catalyst App

A native SwiftUI app that exports everything the public API does expose:

  • All accessories with full metadata
  • Rooms, zones, and scenes
  • All automations and their trigger/condition data
  • Marks shortcut automations (but can’t see inside them)

Method 2: homed Database Extraction (the breakthrough)

A Python script that reads Apple’s internal HomeKit daemon database (~/Library/HomeKit/core.sqlite) and extracts:

  • The full Shortcuts workflow definitions — all your if/then/else blocks
  • Device actions inside shortcuts — every light turn-on, lock unlock, etc.
  • Conditional logic — toggle patterns, multi-branch menus, nested conditions

The trick: Apple’s homed daemon stores everything in a CoreData SQLite database, encoded in binary plists and protobuf. Three layers deep, but all decodable with Python stdlib.

Method 3: Automated Home Assistant Conversion

Combine both exports and convert everything to HA automation YAML automatically:

  • Entity mapping from HomeKit accessory names to HA entity IDs
  • Characteristic translation (brightness, color, temperature → HA service calls)
  • Conditional logic preservation
  • Occupancy and “party mode” conditions

What You Get

A merged JSON export with every automation fully decoded, then converted to Home Assistant YAML.

Real-world example: I extracted 207 HomeKit automations, mapped 272 accessories to HA, and converted 177 of them to working HA automations with 1,964 service calls — automations that previously looked like a black box.

Quick Start

Prerequisites

  • Mac with HomeKit configured (on the same iCloud account as your Home)
  • Xcode 15+ and XcodeGen
  • Python 3.9+ (stdlib only — no pip packages)
  • Full Disk Access granted to Terminal (System Settings > Privacy & Security)

Steps

  1. Build & run the Catalyst app:

    cd app
xcodegen generate
open HomeKitDumper.xcodeproj
# Build & Run (Cmd+R) for "My Mac (Designed for iPad)"
# Click "Export HomeKit Data" → homekit_export.json

  2. Extract the homed database:

    cd scripts
python3 homed_extract.py -o homekit_homed_export.json

  3. Merge both exports:

    python3 merge_exports.py \
  --app-export ../homekit_export.json \
  --homed-export homekit_homed_export.json \
  -o homekit_merged.json

  4. Convert to Home Assistant (optional):

    # Copy your HA entity registry first
# (/config/.storage/core.entity_registry from your HA instance)

python3 homekit_to_ha.py \
  --export homekit_merged.json \
  --entity-registry core.entity_registry \
  -o homekit_automations.yaml

Then paste the YAML into your automations and tweak as needed.

Key Limitations

  • Read-only — This extracts data, doesn’t write it back to HomeKit
  • macOS only — The homed database is only on macOS. (The Catalyst app works on both.)
  • Full Disk Access required — The database is TCC-protected
  • Protobuf UUIDs can’t be resolved — Device references inside shortcuts use an isolated UUID namespace, so the script falls back to name-based matching
  • Local data only — Reads your Mac’s database copy. If your Home Hub hasn’t synced recently, data may be stale.

Documentation

Full details in the repo:

  • SCHEMA.md — Complete homed database schema
  • DISCOVERY.md — How I reverse-engineered the homed approach
  • CONVERSION.md — Conversion logic & HomeKit ↔ HA mapping

Privacy & Security

Everything runs locally. No network calls, no telemetry, no credentials. The homed database is opened read-only. Scrub your export before sharing (it contains device names, rooms, and automation logic).

GitHub

github.com/tamengual/homekit-extractor

License: MIT

Have a complex HomeKit setup you’re migrating to HA? This tool should handle it. If you hit edge cases or want to contribute (better UUID resolution, iOS extraction, more workflow action types), issues and PRs welcome.

1 Like
2

That is very cool! I wish I had it back when I moved from HK to HA. You should consider a reverse (HK Injector?) that will mirror HA controls back through to HK. I still maintain HomeKit for my wife who simply prefers it because I made her use it before I started with HomeAssistant.