FindMySyncPlus

Publish Apple Find My locations to Home Assistant — devices, items, and friends — privately, locally, no third-party services.

FindMySyncPlus reads your encrypted Find My cache files, decrypts them, and posts location updates directly to your Home Assistant instance on a configurable schedule. No cloud relay. No tracking service. Your Find My data goes straight to your home network and nowhere else.

It tracks Devices (iPhones, Apple Watch), Items (AirTags), and Friends — including live friend coordinates by decrypting LocalStorage.db, something no other tool supports. Supports both REST (device_tracker/see) and MQTT (with HA auto-discovery and rich attributes) transports. Rotating UUIDs are handled automatically, and all sensitive credentials are stored securely in the macOS Keychain.

Based on FindMySync and the decryption research by Pnut-GGG.

If you're coming from FindMySync — this is the version that works on macOS 15+.

---

Why FindMySyncPlus?

	FindMySyncPlus	FindMySync (original)	iCloud3
macOS 15+ (Sequoia) support	✅	❌	➖
AirTag / Items support	✅	✅	❌
Friend location tracking	✅	❌	❌
Auto-refresh Find My (no AppleScript)	✅	❌	➖
Auto-learn rotating UUIDs	✅	❌	➖
HA Mobile App on tracked devices	Not required	Not required	⚠️ Recommended
Connects to Apple iCloud API	➖	➖	✅
Runs inside Home Assistant	❌ Requires a Mac	❌ Requires a Mac	✅
Initial setup complexity	🟡 Moderate (key extraction)	🟢 Low	🔴 High
Ongoing configuration	🟢 Low	🟢 Low	🔴 High
Update frequency	Configurable (≥1 min)	External AppleScript	Near real-time

---

Features

• Tracks Devices (iPhone, Apple Watch), Items (AirTags), and Friends
• Two transport modes — REST (device_tracker/see) or MQTT with Home Assistant auto-discovery
• MQTT rich attributes — altitude, speed, course, motion state, location labels via json_attributes_topic
• Friend location tracking — decrypts LocalStorage.db for live friend coordinates; family members already tracked via Devices are automatically deduplicated using Apple's universal person identifier (DSID)
• Device Manager — assign friendly aliases to devices, items, and friends; aliases become stable HA entity IDs even as UUIDs rotate
• Auto-learn UUIDs — automatically re-maps devices when Apple rotates their identifier
• Configurable scheduler with selectable refresh interval and manual Run Now and Dry Run modes
• Four log levels (Error / Warn / Info / Debug) with per-run statistics — posted updates, warnings, learned UUIDs
• Optionally auto-launches Find My to refresh cache before each sync — no AppleScript required
• All credentials (encryption key, HA token) stored in the macOS Keychain
• Menu bar agent — runs silently in the background with open-at-login support
• Full Disk Access gating with clear in-app guidance when permission is missing

---

Friend Location Tracking

FindMySyncPlus is the only tool that tracks friend locations from Apple Find My. Apple discontinued the Find My Friends (FMF) API, and live friend coordinates are not available in the .data cache files that other tools read. The only remaining source is LocalStorage.db — an encrypted SQLite database owned by findmylocateagent.

FMS+ decrypts this database using the same AES-256 keystream XOR cipher that Apple's libsqlite3 codec uses internally, discovered by reverse-engineering the sqliteCodecCCCrypto function.

Family member dedup & enrichment — Family members appear in both Devices.data (as shared devices) and LocalStorage.db (as friends). FMS+ automatically detects this overlap using Apple's universal person identifier (DSID) and skips duplicates, so each family member is only tracked once. Rich attributes from LocalStorage (altitude, speed, course, motion state) are merged onto the FMIP device entry, giving family members the best of both sources.

Setup: Import LocalStorage.key in the Access Settings tab (extracted alongside the other keys in Phase 1) — the Friends source auto-enables when the key is imported.

---

Screenshots

---

Requirements

• macOS 15 (Sequoia) or higher
• A running Home Assistant instance — either the device_tracker.see REST API or an MQTT broker (e.g. Mosquitto add-on)
• Find My encryption keys extracted from Keychain (see Phase 1 below)

---

Getting Started

Phase 1 — Extract Keys

Extract your Find My encryption keys using findmy-key-extractor. This is a one-time step — keys are stable across reboots. Requires temporarily disabling SIP + AMFI; see the extractor README for the full procedure.

The extractor saves all three keys to a keys/ folder:

Key file	Enables
keys/FMIPDataManager.bplist	Required — device and item tracking (core feature)
keys/FMFDataManager.bplist	Friend metadata
keys/LocalStorage.key	Friend location tracking

Import all three in the Access settings tab (Phase 3) — select the All tab under Decryption Keys and click Import All from Folder, then point it at the keys/ directory.

Phase 2 — Install

Download the latest .dmg from Releases, open it, and drag FindMySyncPlus to your Applications folder. Right-click → Open the first time to bypass Gatekeeper.

Alternatively, clone the repo and build in Xcode with automatic signing enabled.

Phase 3 — Configure

Launch the app and open the Access pane (the Home screen will show "Not Set" errors — click one):

1. Choose transport mode — MQTT is selected by default. Switch to REST if preferred.
2. MQTT users: Enter your broker host, port, username, and password. Set topic prefix if desired (default: findmysyncplus/). HA auto-discovery creates entities automatically — no known_devices.yaml needed REST users: Enter your HA device_tracker.see endpoint URL and Authorization header (include the Bearer prefix)
3. Click Verify to test the connection
4. Under Decryption Keys, select the All tab and click Import All from Folder — point it at the keys/ directory from Phase 1
5. Click Open Preferences and grant Full Disk Access
6. Quit and relaunch the app

If prompted by Keychain, click Always Allow.

Building from source? You do not need a paid Apple Developer account. A free Apple ID is enough — Xcode calls this a Personal Team and it signs macOS apps indefinitely for local use.

1. In Xcode, go to Xcode → Settings → Accounts and add your Apple ID — Xcode automatically creates a Personal Team and generates a signing certificate for you
2. Select the project in the navigator, open Signing & Capabilities, enable Automatically manage signing, and choose your Personal Team from the Team dropdown
3. Build and run — if Keychain prompts appear, click Always Allow once

See Choosing a Membership for a full comparison of free vs paid Apple Developer accounts.

Under the General pane, recommended settings:

• Enable Open at Login
• Disable Open Main Window on Startup (runs as a menu bar agent)
• Enable Auto-start Scheduler
• Enable Auto-learn UUIDs

Phase 4 — First Run & Device Manager

1. Open the Status pane and set log level to Debug
2. Click Run Now (▶) in the toolbar and review the logs — all discovered devices, items, and friends appear here
3. Open Device Manager and click Assign for each entry you want to track — friends appear with a purple Friend badge
4. Give each entry an alias — the Home Assistant entity will be findmy_<alias>
5. Return to the Home pane and enable the Scheduler

REST users: Optionally edit known_devices.yaml in Home Assistant to add friendly names:

findmy_alias1:
  name: "Alice's AirTag"
  track: true

MQTT users: Entities are created automatically via HA auto-discovery — no known_devices.yaml needed. Rich attributes (altitude, speed, motion state, etc.) are available on each entity's json_attributes.

---

A Note on AI Co-creation

This project was my first experience building software collaboratively with AI — using ChatGPT, Gemini, and Claude as thinking partners throughout the process. It started as a learning exercise and grew into a working tool I run daily. Later versions — including friend location tracking and the LocalStorage.db cipher reverse-engineering — were built exclusively with Claude. The code reflects that journey.

---

Acknowledgements

• FindMySync by Martin Pham — the original project this is based on
• findmy-cache-decryptor by Pnut-GGG — reverse-engineered the Find My .data file encryption
• LocalStorage.db cipher — reverse-engineered from Apple's sqliteCodecCCCrypto in libsqlite3.dylib via lldb disassembly, with Claude
• findmy-key-extractor — extracts all 3 Find My encryption keys required for setup
• Ink — MIT-licensed Markdown parser used in-app
• FollowMyFriends — reference for MQTT transport pattern
• CocoaMQTT — MIT-licensed MQTT client for Swift