hermes-agent/website/docs/user-guide/skills/bundled/apple/apple-findmy.md
treatux 2a1ec15a6f docs(website): regenerate the skill docs from the shipped skill tree
website/scripts/generate-skill-docs.py is the documented source of both catalogs
and of the per-skill pages, but nothing compares its output with what is
committed, so the committed copies drifted:

- optional-skills-catalog.md was missing agent-merge-conflict-arbiter and listed
  pr-lens under blockchain (it lives in software-development);
- skills-catalog.md still listed merge-reconciler, which #98539 moved out of the
  bundled set;
- 196 pages and both catalogs carried Windows path separators — in the Path
  column and inside GitHub blob links, where a backslash is a broken URL.

This commit is the generator's output (re-running it on this branch is a no-op),
plus the orphan page #98539 left behind for merge-reconciler: no skill backs it,
its catalog row is gone, and no page links to it.

tests/skills/test_skill_docs_contract.py is the guard: the next skill that ships
without a catalog row, or a page regenerated on Windows, fails there instead of
on the published page.
2026-09-20 12:54:07 -07:00

4.3 KiB

title sidebar_label description
Findmy — Track Apple devices/AirTags via FindMy.app on macOS Findmy Track Apple devices/AirTags via FindMy.app on macOS

{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Findmy

Track Apple devices/AirTags via FindMy.app on macOS.

Skill metadata

Source Bundled (installed by default)
Path skills/apple/findmy
Version 1.0.0
Author Hermes Agent
License MIT
Platforms macos
Tags FindMy, AirTag, location, tracking, macOS, Apple

Reference: full SKILL.md

:::info The following is the complete skill definition that Hermes loads when this skill is triggered. This is what the agent sees as instructions when the skill is active. :::

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

# 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 ~/.hermes/cache/scratch/findmy.png

Then use vision_analyze to read the screenshot:

vision_analyze(image_url="~/.hermes/cache/scratch/findmy.png", question="What devices/items are shown and what are their locations?")

Switch Between Tabs

# 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'

If peekaboo is installed, use it for more reliable UI interaction:

# Open Find My
osascript -e 'tell application "FindMy" to activate'
sleep 3

# Capture and annotate the UI
peekaboo see --app "FindMy" --annotate --path ~/.hermes/cache/scratch/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 ~/.hermes/cache/scratch/findmy-detail.png

Then analyze with vision:

vision_analyze(image_url="~/.hermes/cache/scratch/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):

# 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 ~/.hermes/cache/scratch/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