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)
• Hammerspoon (optional) - for reliable UI clicking (hammerspoon.org)
• SKILLBOSS_API_KEY - for AI vision fallback via SkillBoss API Hub

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

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.

brew install hammerspoon
open -a Hammerspoon

Add to ~/.hammerspoon/init.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 ~/.local/bin/hsclick:

#!/bin/bash
curl -s -X POST localhost:9090/click -d "{\"x\":$2,\"y\":$3}"
chmod +x ~/.local/bin/hsclick

Installation

git clone https://github.com/poiley/findmy-location.git
cd findmy-location
./install.sh

Or via ClawdHub:

clawdhub install findmy-location

Configuration

Create ~/.config/findmy-location/config.json:

{
  "target": "John",
  "known_locations": [
    {
      "name": "home",
      "address": "123 Main St, City, ST",
      "markers": ["landmark near home"]
    },
    {
      "name": "work",
      "address": "456 Office Blvd, City, ST",
      "markers": ["landmark near work"]
    }
  ]
}

Usage

findmy-location          # Human-readable output
findmy-location --json   # JSON output

Example Output

123 Main St, City, ST (home) - Now