Home Assistant Skill

Query a Home Assistant instance for presence, sensor data, calendar events, and cameras.

Setup

Credentials in .env at your agent workspace root:

HA_HOST=https://<your-ha-host>
HA_API_KEY=<long-lived-access-token>

Cloud connectivity: If your HA instance uses Nabu Casa, the host resolves publicly (CNAME → *.ui.nabu.casa). No /etc/hosts entry or VPN needed.

Generate a long-lived token: HA UI → Profile → Long-Lived Access Tokens → Create.

Quick Commands

HA=gptme-contrib/skills/home-assistant/scripts/ha.py

# Test connectivity
uv run python3 $HA status

# Owner's current location / presence
uv run python3 $HA location

# Full real-world context (location, weather, next event, recent automations)
# — useful before voice calls, standups, or scheduling decisions
uv run python3 $HA context
uv run python3 $HA --json context

# All person/device tracker states
uv run python3 $HA persons

# Upcoming calendar events
uv run python3 $HA calendar

# List all cameras
uv run python3 $HA cameras

# Get any entity state
uv run python3 $HA state <entity_id>

# List all entities (optionally filtered by domain)
uv run python3 $HA states
uv run python3 $HA states --domain sensor
uv run python3 $HA states --domain device_tracker

# JSON output for scripting
uv run python3 $HA location --json

Common Entity ID Patterns

HA entity IDs follow predictable patterns — discover yours with ha.py states:

Domain	Example	Notes
`person.<name>`	`person.alice`	state: home/away/zone_name
`device_tracker.*`	`device_tracker.alice_phone`	GPS source for person entity
`sensor.*_battery_level`	`sensor.alice_phone_battery_level`	%
`calendar.main`	`calendar.main`	Primary Google calendar
`weather.forecast_*`	`weather.forecast_home`	Current weather
`camera.*`	`camera.front_door`	Camera snapshot
`zone.home`	`zone.home`	Home geofence

Use ha.py states --domain sensor to browse what's available on your instance.

REST API Reference

Base URL: $HA_HOST/api/ Auth header: Authorization: Bearer $HA_API_KEY

Key endpoints:

GET /api/states — all entity states
GET /api/states/<entity_id> — single entity
GET /api/config — HA config (location, timezone)
GET /api/calendars/<entity_id>?start=<iso-utc>&end=<iso-utc> — calendar events (note: Z suffix required for UTC, not +00:00)
GET /api/camera_proxy/<entity_id> — camera snapshot (binary JPEG)

Google Calendar (Alternative)

If the agent's Google account is shared as a reader on the owner's main calendar, use gog (gogcli) directly without HA:

# Upcoming events
gog calendar events "<owner-google-account>" --results-only -j

# Compact view
gog calendar events "<owner-google-account>" --results-only -j | python3 -c "
import json, sys
for e in json.load(sys.stdin):
    start = e.get('start', {}).get('dateTime', e.get('start', {}).get('date', '?'))[:16]
    print(f'{start}  {e.get(\"summary\", \"(no title)\")}')
"

Giving Another Agent the Same Capability

SSH to the other agent's VM
Add HA_HOST and HA_API_KEY to their .env
Pull latest gptme-contrib — the script is at gptme-contrib/skills/home-assistant/scripts/ha.py

For Google Calendar: share the owner's calendar with the agent's Google account (reader access).