icloud-findmy

What This Skill Does

The icloud-findmy skill enables your OpenClaw AI agent to interface directly with Apple's Find My infrastructure. By utilizing the pyicloud library, the agent can retrieve real-time telemetry from family devices linked to your iCloud account. This includes precise geographical coordinates, battery health percentages, and current charging status. It essentially turns your AI agent into a personal geolocation assistant, capable of monitoring the whereabouts and power status of authorized devices without manual intervention.

Installation

To begin, ensure you have pipx installed via Homebrew. Execute pipx install pyicloud to establish the core engine. Next, perform a one-time authentication by running the CLI command provided in the setup documentation using your Apple ID. Complete the 2FA prompts to establish a persistent session file in your home directory, which will remain active for 1-2 months. Finally, document your Apple ID in your workspace config (TOOLS.md) so the agent can reference it for future automated lookups.

Use Cases

This skill is perfect for family coordination and device tracking. It is useful for verifying if a family member has arrived safely at school or work, checking if a child's device is dying so you can prompt them to charge it, or locating a misplaced laptop or mobile phone. By automating these lookups, you save time and reduce the friction of constantly checking the Find My app manually.

Example Prompts

1. "Check the battery level of my daughter's iPhone and let me know if it needs charging."
2. "Where is the family's iPad right now? Please give me the coordinates."
3. "Is Liam's iPhone currently charging, and where was it last spotted?"

Tips & Limitations

Note that device names from iCloud can contain specific Unicode characters like curly apostrophes; always normalize your search strings to ensure matching succeeds. Since locations are stored as Python dictionaries, ensure your agent environment is configured to parse these efficiently. Remember that authentication sessions expire periodically; if the agent reports an authentication error, you will need to re-run the CLI login process manually. Lastly, ensure you have enabled location sharing within your Apple Family Sharing settings for all devices you intend to track, otherwise, the API will return restricted or null location data.