132 lines
3.7 KiB
Markdown
132 lines
3.7 KiB
Markdown
---
|
|
name: findmy
|
|
description: Track Apple devices and AirTags via FindMy.app on macOS using AppleScript and screen capture.
|
|
version: 1.0.0
|
|
author: Hermes Agent
|
|
license: MIT
|
|
platforms: [macos]
|
|
metadata:
|
|
hermes:
|
|
tags: [FindMy, AirTag, location, tracking, macOS, Apple]
|
|
---
|
|
|
|
# Find My (Apple)
|
|
|
|
Track Apple devices and AirTags via the FindMy.app on macOS. Since Apple doesn't
|
|
provide a CLI for FindMy, this skill uses AppleScript to open the app and
|
|
screen capture to read device locations.
|
|
|
|
## Prerequisites
|
|
|
|
- **macOS** with Find My app and iCloud signed in
|
|
- Devices/AirTags already registered in Find My
|
|
- Screen Recording permission for terminal (System Settings → Privacy → Screen Recording)
|
|
- **Optional but recommended**: Install `peekaboo` for better UI automation:
|
|
`brew install steipete/tap/peekaboo`
|
|
|
|
## When to Use
|
|
|
|
- User asks "where is my [device/cat/keys/bag]?"
|
|
- Tracking AirTag locations
|
|
- Checking device locations (iPhone, iPad, Mac, AirPods)
|
|
- Monitoring pet or item movement over time (AirTag patrol routes)
|
|
|
|
## Method 1: AppleScript + Screenshot (Basic)
|
|
|
|
### Open FindMy and Navigate
|
|
|
|
```bash
|
|
# Open Find My app
|
|
osascript -e 'tell application "FindMy" to activate'
|
|
|
|
# Wait for it to load
|
|
sleep 3
|
|
|
|
# Take a screenshot of the Find My window
|
|
screencapture -w -o /tmp/findmy.png
|
|
```
|
|
|
|
Then use `vision_analyze` to read the screenshot:
|
|
```
|
|
vision_analyze(image_url="/tmp/findmy.png", question="What devices/items are shown and what are their locations?")
|
|
```
|
|
|
|
### Switch Between Tabs
|
|
|
|
```bash
|
|
# Switch to Devices tab
|
|
osascript -e '
|
|
tell application "System Events"
|
|
tell process "FindMy"
|
|
click button "Devices" of toolbar 1 of window 1
|
|
end tell
|
|
end tell'
|
|
|
|
# Switch to Items tab (AirTags)
|
|
osascript -e '
|
|
tell application "System Events"
|
|
tell process "FindMy"
|
|
click button "Items" of toolbar 1 of window 1
|
|
end tell
|
|
end tell'
|
|
```
|
|
|
|
## Method 2: Peekaboo UI Automation (Recommended)
|
|
|
|
If `peekaboo` is installed, use it for more reliable UI interaction:
|
|
|
|
```bash
|
|
# Open Find My
|
|
osascript -e 'tell application "FindMy" to activate'
|
|
sleep 3
|
|
|
|
# Capture and annotate the UI
|
|
peekaboo see --app "FindMy" --annotate --path /tmp/findmy-ui.png
|
|
|
|
# Click on a specific device/item by element ID
|
|
peekaboo click --on B3 --app "FindMy"
|
|
|
|
# Capture the detail view
|
|
peekaboo image --app "FindMy" --path /tmp/findmy-detail.png
|
|
```
|
|
|
|
Then analyze with vision:
|
|
```
|
|
vision_analyze(image_url="/tmp/findmy-detail.png", question="What is the location shown for this device/item? Include address and coordinates if visible.")
|
|
```
|
|
|
|
## Workflow: Track AirTag Location Over Time
|
|
|
|
For monitoring an AirTag (e.g., tracking a cat's patrol route):
|
|
|
|
```bash
|
|
# 1. Open FindMy to Items tab
|
|
osascript -e 'tell application "FindMy" to activate'
|
|
sleep 3
|
|
|
|
# 2. Click on the AirTag item (stay on page — AirTag only updates when page is open)
|
|
|
|
# 3. Periodically capture location
|
|
while true; do
|
|
screencapture -w -o /tmp/findmy-$(date +%H%M%S).png
|
|
sleep 300 # Every 5 minutes
|
|
done
|
|
```
|
|
|
|
Analyze each screenshot with vision to extract coordinates, then compile a route.
|
|
|
|
## Limitations
|
|
|
|
- FindMy has **no CLI or API** — must use UI automation
|
|
- AirTags only update location while the FindMy page is actively displayed
|
|
- Location accuracy depends on nearby Apple devices in the FindMy network
|
|
- Screen Recording permission required for screenshots
|
|
- AppleScript UI automation may break across macOS versions
|
|
|
|
## Rules
|
|
|
|
1. Keep FindMy app in the foreground when tracking AirTags (updates stop when minimized)
|
|
2. Use `vision_analyze` to read screenshot content — don't try to parse pixels
|
|
3. For ongoing tracking, use a cronjob to periodically capture and log locations
|
|
4. Respect privacy — only track devices/items the user owns
|