findmy-location

---
name: findmy-location
description: Track a shared contact's location via Apple Find My with street-level accuracy. Returns address, city, and context (home/work/out) by reading map landmarks. Supports configurable known locations and vision fallback for unknown places.
---

# Find My Location

Track shared contacts via Apple Find My with street-corner accuracy.

## Requirements

- **macOS** 13+ with Find My app
- **Python** 3.9+
- **iCloud account** signed in on your Mac (for Find My access)
- **Location sharing** enabled from the contact you want to track
- **peekaboo** - screen reading CLI ([GitHub](https://github.com/steipete/peekaboo))
- **Hammerspoon** (optional) - for reliable UI clicking ([hammerspoon.org](https://www.hammerspoon.org/))

## Prerequisites

### 1. iCloud & Find My Setup

Your Mac must be signed into an iCloud account with Find My enabled:
- System Settings → Apple ID → iCloud → Find My Mac (enabled)
- The person you want to track must share their location with this iCloud account via Find My

### 2. Install peekaboo

```bash
brew install steipete/tap/peekaboo
```

Grant **Accessibility** and **Screen Recording** permissions when prompted (System Settings → Privacy & Security).

### 3. Install Hammerspoon (optional but recommended)

Hammerspoon provides reliable clicking that works across all apps. Without it, clicks may occasionally go to the wrong window.

```bash
brew install hammerspoon
open -a Hammerspoon
```

Add to `~/.hammerspoon/init.lua`:
```lua
local server = hs.httpserver.new(false, false)
server:setPort(9090)
server:setCallback(function(method, path, headers, body)
    local data = body and hs.json.decode(body) or {}
    if path == "/click" then
        hs.eventtap.leftClick({x=data.x, y=data.y})
        return hs.json.encode({status="clicked", x=data.x, y=data.y}), 200, {}
    end
    return hs.json.encode({error="not found"}), 404, {}
end)
server:start()
```

Reload config (Hammerspoon menu → Reload Config), then create `~/.lo