location

Files (1)

• SKILL.md

SKILL.md (first lines)

# location — real-time GPS, cross-platform

Auto-detected backend per OS:

| OS | Backend | Accuracy | Permission |
|---|---|---|---|
| macOS | `corelocationcli` (CoreLocation) | cell / WiFi / GPS (meter-level) | System Settings → Privacy & Security → Location |
| Linux | `gdbus` + Geoclue2 | WiFi / Mozilla MLS / kernel-DRM | xdg-desktop-portal dialog (per-app) |
| any | `curl ipapi.co` fallback | city-level only | none (uses your IP) |

Two-tier location story for KinClaw:

| Layer | Where | When to use |
|---|---|---|
| `{{location}}` substitution | Soul prompt, from `$KINCLAW_LOCATION` env | Persistent context — "user lives in Beijing" |
| `location` skill (this) | Tool call to OS location service | Real-time GPS — "user is at $current_lat,$lon" |

The skill is opt-in: not installed → clear error message + install hint.
Already installed → uses the OS's actual location services.

## Privacy

- **macOS**: triggers Apple's standard Location Services permission flow.
  macOS asks ONCE per process; subsequent calls reuse the grant. Revoke
  via System Settings → Privacy & Security → Location Services.
- **Linux**: Geoclue2 uses `xdg-desktop-portal` for permission. On GNOME /
  KDE it prompts via the portal dialog; on Sway/i3 the dialog may not
  appear (in which case grant via `gnome-control-center privacy` once).
- **IP fallback**: no permission needed because no GPS hardware is queried —
  ipapi.co geolocates your public IP. City-level only.

## Usage

```
location                       → "37.7749,-122.4194"
location format=address        → "1 Apple Park Way, Cupertino, CA"
location format=city           → "Cupertino"
location format=full           → multi-line: lat/lon/alt/accuracy/...
```

The backend is auto-selected at invocation time; the agent doesn't need
to know whether it's running on macOS or Linux.

## Linux setup (one-time)

```bash
# Debian / Ubuntu
sudo apt install geoclue-2.0 curl

# Fedora
sudo dnf install geoclue2 curl

# Arch
sudo pacman -S geoclue curl

# Verify geoclue is running
systemctl --user status geoclue.service  # may be system-wide, try without --user too
```

If Geoclue2 doesn't return a fix within 10 seconds (often the case on
servers / Pi without WiFi positioning), the skill auto-falls-back to IP
geolocation. Forge a derivative skill if you want different fallback
behavior (e.g. cache last good fix, exponential retry).

From LocalKinAI/kinclaw, Apache-2.0.

More from LocalKinAI/kinclaw