FindMyPipe – Query Apple Find My from Linux for AI Agents

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

1 Commit

1 Commit

assets

assets

references

references

scripts

scripts

src/findmy_agent_bridge

src/findmy_agent_bridge

tests

tests

.gitignore

.gitignore

LICENSE

LICENSE

README.it.md

README.it.md

README.md

README.md

SKILL.md

SKILL.md

pyproject.toml

pyproject.toml

Repository files navigation

FindMyPipe is a local CLI bridge that queries Apple Find My from Linux and returns device locations as structured JSON, ready for AI agents, shell scripts, and automation pipelines.

Beyond simply knowing where your devices are, findmypipe is designed to power location-aware workflows: given the coordinates of a device, an AI agent can query external services to find nearby points of interest — restaurants, hotels, hospitals, transit stops — and build richer, context-aware experiences.

"Where's my iPhone?" · "Is my MacBook at home?" · "Find a coffee shop near my AirPods" · "What's the nearest hospital to my iPad?"

✨ Features

Feature Description

🔍 Locate Apple devices iPhone, iPad, Mac, AirPods — real-time position via iCloud

📍 Points of interest nearby Feed coordinates to any POI API (Google Places, OSM, Foursquare) to find what's around your device

🖥️ Professional CLI Clean structured JSON output on stdout, easy to pipe and parse

🔐 Privacy-first Redacted credentials in logs, device IDs replaced by SHA-256 hash

📦 Zero configuration Mock mode works out of the box — no Apple ID needed to explore

⏱️ Optional cache Configurable TTL to avoid hammering the iCloud API

🧹 Smart filters --skip-offline and --max-age to keep only fresh, relevant data

🔄 Full 2FA login Complete Apple authentication flow, interactive 2FA included

🤖 AI agent-ready Designed as an AgentSkills.io-compliant skill — plug it into any agent framework

🤖 What is an AgentSkills.io Skill?

FindMyPipe ships with a SKILL.md definition conforming to the AgentSkills.io standard. This means:

Any AI agent framework that supports the standard can automatically discover and invoke this tool

The skill is self-describing: it declares its inputs, outputs, and capabilities in a machine-readable format

It integrates seamlessly with agents like Hermes, custom LLM pipelines, or any shell-capable orchestrator

Think of it as an OpenAPI spec, but for AI agent tools.

💡 Use Cases

🗺️ Find points of interest near your device

Get your iPhone's coordinates

COORDS=$(findmy-agent locate "iPhone" --json | jq -r '"\(.asset.latitude),\(.asset.longitude)"')

Query nearby restaurants (example with Google Places API)

curl "https://maps.googleapis.com/maps/api/place/nearbysearch/json\ ?location=$COORDS&radius=500&type=restaurant&key=$GOOGLE_API_KEY" | jq '.results[].name'

📍 Check if a device is home

findmy-agent locate "MacBook" --json | jq '.asset | {name, latitude, longitude, last_seen}'

🔔 Periodic monitoring via cron

Every 15 minutes, log all online devices

*/15 * * * * findmy-agent list --json --skip-offline >> /var/log/findmy.log

🤖 AI agent integration (Hermes)

~/.hermes/config.yaml

tools:

• name: findmy_locate

cmd: "findmy-agent locate \"{{name}}\" --json"

• name: findmy_list

cmd: "findmy-agent list --json --skip-offline"

• name: findmy_doctor

cmd: "findmy-agent doctor --json"

📦 Installation

Prerequisites

Python 3.11+

Linux (tested) or macOS

An Apple ID with Find My enabled (live mode only)

Quick install

git clone https://github.com/corryl/FindMyPipe.git cd FindMyPipe python3 -m venv .venv

Mock mode only (works immediately, no Apple ID needed)

.venv/bin/pip install -e '.[dev]'

With live iCloud support

.venv/bin/pip install -e '.[dev,live]'

Verify installation

.venv/bin/findmy-agent doctor --json

Expected output:

{ "cache": {"enabled": false, "state": "empty", "ttl_seconds": 0}, "live_probe_available": true, "ok": true, "provider": "mock", "secrets_redacted": true, "transport": "local" }

⚙️ Configuration

Live iCloud mode

export FINDMY_AGENT_PROVIDER="icloud" export FINDMY_APPLE_ID="[REDACTED]" export FINDMY_APPLE_PASSWORD="[REDACTED]"

🔐 Use an app-specific password — Apple ID → Security → App-Specific Passwords. Never use your main Apple ID password.

Optional settings

export FINDMY_COOKIE_DIR="$HOME/.local/state/findmypipe/icloud" export FINDMY_CACHE_TTL="300" # seconds (0 = disabled) export FINDMY_CACHE_FILE="$HOME/.local/state/findmypipe/cache.json"

Interactive login (first run)

findmy-agent login --json

Type your 2FA code when Apple sends it

🖥️ CLI Reference

All commands accept --json for structured output.

findmy-agent doctor

Check bridge status and provider availability.

findmy-agent doctor --json findmy-agent doctor --provider icloud --json

findmy-agent list

List all devices with location, battery level, and last seen time.

findmy-agent list --json findmy-agent list --json --skip-offline --max-age 30 findmy-agent list --json --include-raw

Example output

{ "assets": [{ "id": "icloud:a1b2c3d4e5f6a7b8", "name": "iPhone", "kind": "device", "provider": "icloud", "latitude": 45.1234, "longitude": 9.5678, "accuracy_m": 15.0, "battery": 0.85, "battery_status": "charged", "last_seen": "2025-05-30T12:34:56Z", "location_is_old": false }] }

findmy-agent locate

Search for a specific device by name or ID (case-insensitive).

findmy-agent locate "iPhone" --json findmy-agent locate "AirPods" --json --skip-offline --max-age 60

findmy-agent login

Interactive iCloud authentication with 2FA.

findmy-agent login --json

Common options

Option Description

--provider mock (default) or icloud

--json Structured JSON output

--include-raw Include redacted raw payload (debug)

--max-age Filter positions older than N minutes

--skip-offline Exclude offline devices

Error format

All errors return a consistent structured format:

{"error": "FINDMY_APPLE_ID not set", "error_type": "configuration_error", "ok": false, "secret_safe": true}

🔐 Privacy & Security

No HTTP server — all I/O on stdio, no open ports, no daemon

No webhooks — outbound polling only toward Apple's servers

Credentials never logged — password, 2FA codes, and tokens always redacted

Hashed device IDs — real identifiers replaced by SHA-256 hash in all output

Raw payload hidden by default — requires explicit --include-raw flag

Restrictive file permissions — directories 0700, files 0600

~/.local/state/findmypipe/ ├── icloud/ # Cookies & sessions (0700) └── cache.json # Optional cache (0600)

🏗️ Architecture

┌──────────────────────────────────────┐ │ AI Agent / Shell Script / Terminal │ └────────────┬─────────────────────────┘ │ CLI (stdin/stdout/stderr) ┌────────────▼─────────────────────────┐ │ findmy-agent │ │ │ │ ┌──────────┐ ┌──────────────────┐ │ │ │ CLI │ │ Cache │ │ │ │ (Typer) │ │ (JSON file) │ │ │ └────┬─────┘ └──────────────────┘ │ │ │ │ │ ┌────▼──────┐ │ │ │ Core │ │ │ └────┬──────┘ │ │ │ │ │ ┌────▼──────┐ │ │ │ Provider │ │ │ │ Mock│iCld │ │ │ └───────────┘ │ └────────────┬─────────────────────────┘ │ HTTPS (outbound only) ┌────────────▼─────────────────────────┐ │ Apple iCloud API │ └──────────────────────────────────────┘

🧪 Tests

.venv/bin/pytest -q --tb=short

tests/test_cache.py .......... tests/test_cli.py .... tests/test_core.py ........ tests/test_icloud_provider.py ... tests/test_provider_factory.py ... 31 passed

📋 Limits & Roadmap

Aspect Status

iPhone, iPad, Mac, AirPods ✅ Supported

AirTag / Items ⏳ Not yet supported

Linux ✅ Tested

macOS ✅ Should work

Interactive 2FA ✅ Supported

POI integration (built-in) ⏳ Planned

📄 License

MIT — see LICENSE.

Built with ❤️ for the AI community · AgentSkills.io · Skill Definition

Local. Secure. Private. Your data, under your control.

About

Local CLI bridge for Apple Find My / Dovè polling from Linux, designed for AI agents.

Topics

python

linux

cli

apple

automation

location

icloud

ai-agents

findmy

agentskills

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 98.2%

Shell 1.8%