findmy-cli 0.1.0

package/openclaw.plugin.json

@@ -0,0 +1,36 @@
+{
+  "id": "findmy-cli",
+  "name": "Find My",
+  "description": "macOS-only. Query Find My friend locations by driving FindMy.app via screen capture and Vision OCR. Returns name, coarse location (city, state), staleness, and distance. Shells out to the `findmy` binary (install via `brew install omarshahine/tap/findmy-cli`). Requires Screen Recording permission granted to the host process.",
+  "version": "0.1.0",
+  "platforms": [
+    "darwin"
+  ],
+  "requires": {
+    "binaries": [
+      "findmy",
+      "findmy-helper"
+    ],
+    "osPermissions": [
+      "macos:screen-recording"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "cliPath": {
+        "type": "string",
+        "description": "Path to the findmy binary. Defaults to PATH lookup.",
+        "default": "findmy"
+      }
+    },
+    "additionalProperties": false
+  },
+  "uiHints": {
+    "cliPath": {
+      "label": "CLI Path",
+      "help": "Path or command name for the findmy binary. Defaults to finding it on PATH (typically /opt/homebrew/bin/findmy after `brew install omarshahine/tap/findmy-cli`).",
+      "placeholder": "findmy"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "findmy-cli",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for macOS Find My friend locations. Shells out to the findmy CLI to drive FindMy.app via screen capture and Vision OCR. macOS-only. Install findmy first via `brew install omarshahine/tap/findmy-cli`.",
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.23"
+    },
+    "build": {
+      "openclawVersion": "2026.4.15"
+    },
+    "environment": {
+      "binaries": [
+        "findmy",
+        "findmy-helper"
+      ],
+      "osPermissions": [
+        "macos:screen-recording"
+      ]
+    },
+    "hostTargets": [
+      "darwin-arm64",
+      "darwin-x64"
+    ]
+  },
+  "files": [
+    "src/",
+    "skills/",
+    "openclaw.plugin.json"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "findmy",
+    "location",
+    "macos",
+    "ocr",
+    "vision",
+    "screen-scraping"
+  ],
+  "author": {
+    "name": "Omar Shahine",
+    "email": "omar@shahine.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omarshahine/findmy-cli.git",
+    "directory": "openclaw"
+  },
+  "homepage": "https://github.com/omarshahine/findmy-cli#readme",
+  "bugs": {
+    "url": "https://github.com/omarshahine/findmy-cli/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.49",
+    "openclaw": "^2026.3.23"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "plugin:check": "npx --yes @openclaw/plugin-inspector inspect --no-openclaw",
+    "plugin:ci": "npx --yes @openclaw/plugin-inspector ci --no-openclaw --runtime --mock-sdk --allow-execute"
+  }
+}

package/skills/findmy/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: findmy
+description: |
+  Query Find My friend locations on macOS via the findmy-cli plugin tools.
+  Returns name, coarse location, staleness, and distance for everyone in
+  the FindMy.app People sidebar. Use when the user asks "where is X", "is
+  X home", "how far is X", or wants a location refresh.
+---
+
+# Find My Location Query
+
+Two tools available, both shell out to the `findmy` binary which drives
+FindMy.app via screen capture and Vision OCR.
+
+## When to use
+
+- "Where is Omar?"        → call `findmy_person` with `name: "Omar"`
+- "Is Sarah home yet?"    → call `findmy_person` with `name: "Sarah"`
+- "How far away is Mike?" → call `findmy_person` with `name: "Mike"`
+- "Anyone near downtown?" → call `findmy_people`, then read the locations
+- "Where is everyone?"    → call `findmy_people`
+
+## Output shape
+
+```json
+[
+  {
+    "name": "Omar Shahine",
+    "location": "Redmond, WA",
+    "staleness": "Paused",
+    "distance": "7 mi"
+  }
+]
+```
+
+- `name` — display name as shown in the FindMy sidebar
+- `location` — city, state (or device label when sharing from a device)
+- `staleness` — `"Now"`, `"X min. ago"`, `"X hr. ago"`, `"Paused"`, `""` (live)
+- `distance` — distance from this Mac if FindMy shows it (e.g. `"7 mi"`)
+
+## Caveats to surface to the user
+
+- **`staleness: "Paused"`** means the friend paused location sharing. The
+  reported location is the last known position, possibly hours or days old.
+  Lead with this when reporting the result.
+- **Stale staleness** (`"7 hr. ago"`, etc.) means the device hasn't checked
+  in recently — phone may be off, in low-power mode, or out of signal.
+- **Focus steal**: each invocation briefly raises FindMy.app to the front.
+- **Back-to-back races**: two findmy calls within ~5s can fail. Space them
+  out when iterating.
+
+## Install requirement
+
+The plugin shells out to the `findmy` binary. If a tool returns
+`"findmy not found on PATH"`, the binary isn't installed. Install with:
+
+```bash
+brew install omarshahine/tap/findmy-cli
+```
+
+After install, grant **Screen Recording** to the host process running this
+plugin (System Settings → Privacy & Security → Screen Recording). Without
+it, FindMy.app captures will return blank.

package/src/index.ts

@@ -0,0 +1,165 @@
+/**
+ * OpenClaw plugin entry for findmy-cli.
+ *
+ * Registers two tools that shell out to the `findmy` binary to query Find My
+ * friend locations on macOS. The CLI drives FindMy.app via screen capture
+ * and Vision OCR — see the host repo for the underlying mechanism.
+ */
+
+import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import { Type } from '@sinclair/typebox';
+import { execFileSync, execFile } from 'child_process';
+import { promisify } from 'util';
+import { existsSync } from 'fs';
+
+const execFileAsync = promisify(execFile);
+
+interface PluginConfig {
+	cliPath?: string;
+}
+
+interface ToolDef {
+	name: string;
+	description: string;
+	parameters: ReturnType<typeof Type.Object>;
+	buildArgs: (params: Record<string, unknown>) => string[];
+}
+
+const TOOLS: ToolDef[] = [
+	{
+		name: 'findmy_people',
+		description:
+			'List every friend in the FindMy.app People sidebar. Returns name, coarse location (city, state), staleness, and distance for each person. Use for "who is where", "anyone near downtown", or any broad location query. Each entry includes a `staleness` field — if "Paused", the friend has paused location sharing and the location is the last known position.',
+		parameters: Type.Object({}),
+		buildArgs: () => ['people', '--json'],
+	},
+	{
+		name: 'findmy_person',
+		description:
+			'Look up a single friend by name (case-insensitive substring match). Returns the same shape as findmy_people but filtered. Use for "where is X", "is X home", "how far is X". Match works on partial names — "sarah" matches "Sarah Shahine".',
+		parameters: Type.Object({
+			name: Type.String({
+				description: 'Friend name or substring (case-insensitive).',
+			}),
+		}),
+		buildArgs: (params) => ['person', String(params.name), '--json'],
+	},
+];
+
+function toolResult(text: string) {
+	return {
+		content: [{ type: 'text' as const, text }],
+		details: undefined,
+	};
+}
+
+function whichBinary(name: string): string | null {
+	const cmd = process.platform === 'win32' ? 'where.exe' : 'which';
+	try {
+		const result = execFileSync(cmd, [name], { encoding: 'utf8' }).trim();
+		const first = result.split('\n')[0]?.trim();
+		return first || null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Resolve the findmy binary:
+ * 1. Plugin config cliPath
+ * 2. Env var FINDMY_CLI_PATH
+ * 3. PATH lookup
+ */
+function resolveCliPath(config?: PluginConfig): string {
+	if (config?.cliPath && existsSync(config.cliPath)) {
+		return config.cliPath;
+	}
+
+	const envPath = process.env.FINDMY_CLI_PATH;
+	if (envPath && existsSync(envPath)) {
+		return envPath;
+	}
+
+	const found = whichBinary('findmy');
+	if (found) return found;
+
+	throw new Error(
+		'findmy not found on PATH. Install with: brew install omarshahine/tap/findmy-cli\n' +
+			'Or set FINDMY_CLI_PATH or configure cliPath in plugin settings.'
+	);
+}
+
+export default definePluginEntry({
+	id: 'findmy-cli',
+	name: 'Find My',
+	description: 'Query Find My friend locations on macOS via UI scraping',
+
+	register(api) {
+		const config = api.pluginConfig as PluginConfig | undefined;
+
+		let cliPath: string;
+		try {
+			cliPath = resolveCliPath(config);
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			for (const tool of TOOLS) {
+				api.registerTool({
+					name: tool.name,
+					label: tool.name,
+					description: tool.description,
+					parameters: tool.parameters,
+					async execute() {
+						return toolResult(
+							JSON.stringify({ success: false, error: errorMessage }, null, 2)
+						);
+					},
+				});
+			}
+			return;
+		}
+
+		for (const tool of TOOLS) {
+			api.registerTool({
+				name: tool.name,
+				label: tool.name,
+				description: tool.description,
+				parameters: tool.parameters,
+
+				async execute(_id: string, params: Record<string, unknown>) {
+					try {
+						const args = tool.buildArgs(params);
+						const { stdout } = await execFileAsync(cliPath, args, {
+							encoding: 'utf8',
+							// FindMy.app capture is slow on cold boot — it has to launch,
+							// switch tabs, render the sidebar, and OCR a screenshot.
+							timeout: 60_000,
+							maxBuffer: 4 * 1024 * 1024,
+						});
+
+						if (stdout.trim().length === 0) {
+							return toolResult(JSON.stringify({ success: true }, null, 2));
+						}
+
+						let result: unknown;
+						try {
+							result = JSON.parse(stdout);
+						} catch {
+							result = { output: stdout.trim() };
+						}
+						return toolResult(JSON.stringify(result, null, 2));
+					} catch (error: unknown) {
+						const message = error instanceof Error ? error.message : String(error);
+						const stderr =
+							error && typeof error === 'object' && 'stderr' in error
+								? String((error as { stderr: unknown }).stderr).trim()
+								: '';
+						const errorOutput = stderr ? `${message}\n\nstderr: ${stderr}` : message;
+						return toolResult(
+							JSON.stringify({ success: false, error: errorOutput }, null, 2)
+						);
+					}
+				},
+			});
+		}
+	},
+});