openclaw-findmy

findmy-cli

Read your Find My people, device, and item locations from the macOS FindMy.app via UI scraping. Apple does not expose a public API for Find My locations and the on-disk caches are encrypted with keychain-bound keys, so this tool drives the GUI: it activates FindMy.app, switches to the People, Devices, or Items tab, screenshots the window, and runs Vision OCR on the result.

Privacy & consent. This is read-only and consent-bounded. It can only see the people who have already opted in to share their location with this Mac's Apple ID in Apple's Find My, plus your own devices and items. It returns coarse location only (city/state, staleness, distance), bypasses no Apple access control, and initiates no network traffic — everything stays on-device. Use it to locate consenting friends and family, not to monitor or track anyone without their knowledge and consent.

Why a Go CLI plus a Swift helper

The macOS APIs we need (Vision, CoreGraphics window list, CGEvent click) have no Go binding. We bundle a tiny Swift binary findmy-helper that exposes them as JSON-emitting subcommands, and a Go CLI findmy that orchestrates.

Install

Pick the channel that matches how you'll use it:

Goal	Channel	Command
Use findmy CLI from terminal	Homebrew	brew install omarshahine/tap/findmy-cli
Use as OpenClaw plugin (chat tools)	ClawHub	clawhub install findmy-cli
Use as Claude Code plugin	OpenClaw	openclaw plugins install --link ~/GitHub/findmy-cli
Use as a Node library	NPM	npm install findmy-cli
Hack on the code	Source	git clone … && make

Homebrew (CLI)

brew install omarshahine/tap/findmy-cli

Installs findmy and findmy-helper to /opt/homebrew/bin/. macOS only. Tap source: omarshahine/homebrew-tap. First run will prompt for Screen Recording permission.

ClawHub (OpenClaw plugin)

clawhub install findmy-cli

Registers findmy_people and findmy_person as OpenClaw tools. Shells out to the findmy binary — install that via Homebrew first. Listing: clawhub.com/p/findmy-cli · NPM package: findmy-cli.

Source build

make

Outputs bin/findmy and bin/findmy-helper.

Requirements:

• macOS (tested on 15+; FindMy.app is a Catalyst app)
• Go 1.22+
• Xcode Command Line Tools (swiftc)

Usage

# List people in the sidebar with coarse location, staleness, distance.
findmy people
findmy people --json
findmy people --no-log

# Click a row and OCR the detail pane (precise address).
findmy person "Omar Shahine"
findmy person "Omar Shahine" --json

# List devices in the sidebar.
findmy devices
findmy devices --json

# Read one matching device.
findmy device "Omar's iPhone"
findmy device "Omar's iPhone" --json

# List items in the sidebar.
findmy items
findmy items --json

# Read one matching item.
findmy item "AirPods Pro"
findmy item "AirPods Pro" --json

# Query the SQLite history ledger populated by people/devices runs.
findmy log "Omar Shahine" --since=24h
findmy log "Omar's iPhone" --kind=devices --limit=10 --json

Successful findmy people, findmy devices, and findmy items runs append parsed sidebar records to a local SQLite ledger before printing output. Pass --no-log to skip a write for one invocation. The default database path is $XDG_DATA_HOME/findmy-cli/history.sqlite, or ~/.local/share/findmy-cli/history.sqlite when XDG_DATA_HOME is unset. Set FINDMY_HISTORY_DB=/path/to/history.sqlite to override it.

FindMy.app menu, tab, and sidebar labels are localized on non-English macOS installs. The CLI auto-detects the current macOS language for the supported FindMy.app strings, and FINDMY_LANG=fr can be used to force a locale for testing.

Required macOS permissions

Grant to the terminal emulator (or to findmy once installed system-wide):

• Screen Recording — for screencapture
• Accessibility — for osascript menu clicks

Settings → Privacy & Security → Screen Recording / Accessibility.

After granting, fully quit and relaunch the host process — TCC is read once at process start.

Running on a headless Mac

FindMy.app needs WindowServer compositing to render its window. WindowServer only runs when macOS sees a display, so a Mac mini / Studio / Pro with nothing plugged into HDMI or USB-C will return a 99 KB all-black PNG every time you call screencapture, even though the process itself runs fine.

To make findmy work headless:

1. Plug in a dummy display. A 4K HDMI/USB-C "headless adapter" (~$10 on Amazon, search "4K HDMI dummy plug" or "USB-C dummy display"). macOS sees it as a real 4K@60Hz monitor and starts WindowServer normally.

2. Disable display sleep so WindowServer stays compositing: