gptme/gptme-contrib/home-assistant

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:

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

1. SSH to the other agent's VM
2. Add HA_HOST and HA_API_KEY to their .env
3. 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).