Location Awareness

This skill provides commands to execute. When the user asks about location, RUN the appropriate command below.

⚠️ IMPORTANT: All commands use scripts/location.sh

Every command must be run via scripts/location.sh. Example:

User asks: "How long to walk home?"
You run:

scripts/location.sh eta home --mode walk

Output: 4.6 km, about 45 min walk
You reply with the output directly.

Do NOT run eta or other subcommands directly — they don't exist as standalone commands.

Quick Reference — What to Run

Response style: Terse. No preamble. No "Here's your location:". Just the answer.

All Commands

All via scripts/location.sh <command>:

Note: eta accepts saved place names, coordinates (lat,lon), or any place name (geocoded via OpenStreetMap, biased to current location).

Note: status returns the zone name if in a known place, otherwise reverse geocodes to a street address (e.g., "123 Main Street, Downtown").

Concepts

Geofences — Saved places with lat/lon, radius, and optional action. Persistent.

Reminders — One-shot alerts tied to a place. Deleted after delivery.

Region/Category — Optional tags for filtering (e.g., "downtown", "pub").

Setup (for administrators)

Provider Configuration

Edit scripts/config.json:

Home Assistant (default):

{
  "provider": "homeassistant",
  "homeassistant": {
    "url": "https://your-ha.example.com",
    "token": "your-long-lived-token",
    "entity_id": "device_tracker.phone"
  }
}

OwnTracks:

{
  "provider": "owntracks",
  "owntracks": {
    "url": "https://owntracks.example.com",
    "user": "username",
    "device": "phone"
  }
}

Generic HTTP:

{
  "provider": "http",
  "http": {
    "url": "https://your-api.com/location",
    "headers": {"Authorization": "Bearer token"}
  }
}

GPSLogger (file-based):

{
  "provider": "gpslogger",
  "gpslogger": {
    "file": "/path/to/location.json"
  }
}

Secrets support: "env:VAR", "pass:path", "cmd:command", or plain string.

Alternative: Set HA_URL and HA_TOKEN environment variables instead of editing config.json.

Output format: Most query commands output human-readable text by default. Add --json for JSON output (useful for scripting).

Travel Speeds

Customize walking/biking speeds for ETA calculations in scripts/config.json:

{
  "speeds_kmh": {
    "walk": 6,
    "bike": 15
  }
}

Geofence Config

Edit scripts/geofences.json:

{
  "geofences": [
    {
      "id": "grocery",
      "name": "Grocery Store",
      "lat": 40.7128,
      "lon": -74.0060,
      "radius_m": 30,
      "action": "shopping_tasks",
      "cooldown_hours": 4,
      "enabled": true,
      "region": "downtown",
      "category": "shop"
    }
  ],
  "location_reminders": [],
  "proximity_alerts": []
}

Cron Setup (Automatic Notifications)

For automatic location-based notifications, set up a systemd timer:

1. Configure notification target (env var):

export CLAWDBOT_NOTIFY_TARGET="+1234567890"  # or @telegram_user, etc.

2. Create systemd service (~/.config/systemd/user/location-check.service):

[Unit]
Description=Location check

[Service]
Type=oneshot
Environment=CLAWDBOT_NOTIFY_TARGET=+1234567890
ExecStart=%h/clawd/skills/location-awareness/scripts/location_cron.sh

3. Create timer (~/.config/systemd/user/location-check.timer):

[Unit]
Description=Run location check every 5 minutes

[Timer]
OnBootSec=2min
OnUnitActiveSec=5min

[Install]
WantedBy=timers.target

4. Enable: systemctl --user enable --now location-check.timer

Notifications use clawdbot message send, so they work with any configured channel (Signal, Telegram, etc.).