ha-automation-explorer

HA Automation Explorer

Read-only. No writes, no proposals, no actuation.

Shared preamble (all modes)

1. Read operator language from OPERATOR.md (## HA hermit section). Use this locale for all output.
2. Read .claude-code-hermit/raw/snapshot-ha-normalized-latest.json. Check the file's mtime with stat. If missing or older than 24 hours, append this warning to all output:

   "Context snapshot is stale — run /claude-code-homeassistant-hermit:ha-refresh-context for accurate entity data."

3. Extract entity_index and silence_summary from the snapshot. Build the automation list: all entries in entity_index whose key starts with automation..

Mode 1 — List all automations

Invoked as /claude-code-homeassistant-hermit:ha-automation-explorer (no args).

1. If the automation list is empty, output: "No automations found in the context snapshot." Stop.
2. Group automations by topic, inferring from friendly_name (from attributes.friendly_name) and entity_id. Buckets (best-effort — no area registry exists):
   • Security: alarm, lock, door, gate, camera, motion, presence
   • Comfort: climate, temperature, heating, cooling, fan, blind, curtain, cover
   • Presence: arrive, leave, away, home, person
   • Energy: power, energy, solar, charge, saving
   • Other: anything that doesn't fit the above
3. Derive a one-line description from friendly_name for each automation. Do not fetch configs here.
4. Mark automations that appear in silence_summary.dead_automations with ⚠ dead (N days). For never_fired: true entries, use ⚠ never fired.
5. Output the catalog grouped by topic:

   **Security**
   - automation.alarm_away — "Arm alarm when everyone leaves" ⚠ dead (12 days)
   
   **Comfort**
   - automation.morning_blinds — "Open blinds at sunrise"
   

Mode 2 — Explain automations matching a keyword

Invoked as /claude-code-homeassistant-hermit:ha-automation-explorer <keyword>.

1. Filter the automation list: keep entries where keyword appears (case-insensitive) in friendly_name or entity_id.
2. If no matches: output "No automations matching ''." Stop.
3. If more than 8 matches, the keyword is too broad to explain at once. List the matching entity_id + friendly_name pairs and ask the operator to narrow the keyword. Do not fetch any configs. Stop.
4. For each match, check attributes.id. If null (YAML-packaged automation, not retrievable via REST), note: "Config not retrievable — automation is YAML-packaged." Skip the config fetch for that entry.
5. For each match with a numeric id, fetch its config:

   ${CLAUDE_PLUGIN_ROOT}/bin/ha-agent-lab ha get-automation-config <id>
   

6. Explain the fetched YAML in plain language in the operator's locale:
   • Triggers: what starts this automation (time, state change, event, etc.)
   • Conditions: any guards that must be true for it to run
   • Actions: what it does, step by step
   • State: enabled / disabled; ⚠ dead if in silence_summary.dead_automations