Family Location Tracker

A cron job tracks where each family member currently is — at home, traveling, or in transit — and writes the result to a shared state file that every agent and automation can read. Nothing else has to query trip data directly.

How It Works

travel-hub agent (cron, 2x daily)
        ↓
  query trip itinerary
        ↓
  resolve city / country / timezone per family member
        ↓
  write familyLocations to heartbeat-state.json
        ↓
  consumed by: agent heartbeats, Eight Sleep Away mode,
               proactive reminders, etc.

The cron runs twice a day at 05:00 and 14:00 UTC, covering morning in both US Pacific and European timezones. Non-travelers default to home locations.

Data Shape

The cron writes a familyLocations block to heartbeat-state.json:

{
  "familyLocations": {
    "owner": {
      "city": "Seattle",
      "country": "US",
      "timezone": "America/Los_Angeles",
      "source": "home"
    },
    "partner": {
      "city": "Lisbon",
      "country": "PT",
      "timezone": "Europe/Lisbon",
      "source": "Lisbon May 2026"
    }
  }
}

source is one of: home, the trip name, or a flight number while in transit.

Trip Status Filtering

A trip only counts as active when its status is Planned. Completed and cancelled trips no longer hold the location pinned to the trip’s last city — important because itinerary queries return trips by date overlap regardless of status.

Consumers

Anything that wants to know “is the family home” reads familyLocations from heartbeat state instead of querying the travel system directly:

Agent heartbeats — every agent reads family locations on each cycle, so timezone-aware suggestions work without an explicit lookup.
Eight Sleep Away mode — flips the bed to Away when both family members leave home and back to Home when either returns.
Proactive reminders — adjust delivery timing to the recipient’s local time when they’re traveling.

Pattern: heartbeat-state.json for Cross-Agent State

heartbeat-state.json is the canonical place to share state across sessions and agents. Pattern:

One writer cron computes the state from authoritative sources.
Many reader agents read it during heartbeats — cheap, no API calls.
Idempotent checks so the writer can run any number of times without side effects.
Only-on-change announcements — readers compare to the previous value and announce only on transitions.

This keeps cross-agent state cheap, observable in one file, and easy to debug.