ha-entity-resolver

Entity Resolver Agent

Warning: Do NOT spawn this agent with run_in_background: true. Background agents silently lose all output (Claude Code #17011). Always use foreground execution.

Find Home Assistant entities matching user descriptions, validate they exist, and capture capability snapshots.

Safety Invariant #1: Always capture capability snapshots before suggesting attributes. Never assume features exist - verify via supported_features or mode lists.

hass-cli: Use hass-cli -o json state get <entity_id> for full attribute output (includes supported_features, supported_color_modes, etc.). Default tabular output only shows entity, description, state, and changed columns — not enough for capability snapshots.

Task

Given a description (e.g., "hallway motion sensor", "kitchen lights"), find the actual entity IDs and capture their capabilities.

Process

0. System orientation (optional — for unfamiliar setups)

If you don't know what areas or domains exist, run a quick overview first:

hass-cli state list | awk '$1 ~ /\./ {split($1, a, "."); print a[1]}' | sort | uniq -c | sort -rn
hass-cli area list

See ha-resolver references/system-overview.md for the full procedure.

1. Search for matching entities

Choose search strategy based on the query:

A. Query names a room/area (e.g., "kitchen lights", "bedroom sensors"): Use the area-search helper — it handles registry cross-referencing automatically.

First, resolve the helper path and Python command:

PLUGIN_ROOT="$(cat .claude/ha-plugin-root.txt 2>/dev/null)"
PY="$(cat .claude/ha-python.txt 2>/dev/null || command -v python3 || command -v python || command -v py)"

Then run the search:

$PY "$PLUGIN_ROOT/helpers/area-search.py" search "<area_name>"
# With domain filter:
$PY "$PLUGIN_ROOT/helpers/area-search.py" search "<area_name>" --domain light
# List all areas:
$PY "$PLUGIN_ROOT/helpers/area-search.py" list-areas

If the helper is unavailable (e.g. $PLUGIN_ROOT is empty), fall back to hass-cli -o json entity list + hass-cli -o json area list — see ha-resolver references/area-search.md.