| name | ha-automations |
| description | Use when writing, editing, debugging, or verifying Home Assistant automations with an agent: "write an automation that...", turn an English description into automation YAML, edit automations.yaml over SSH, an automation that never fires or fired once and went dead, a service call that silently did nothing, testing with automation.trigger, or reloading automations without restarting Core. Covers the write → check → reload → verify loop and the silent-failure traps (event-entity triggers, dead notify services, no-op writes). Not for the initial connection (ha-connect) or price/LLM-driven triggers (ha-external-triggers). |
| compatibility | Home Assistant with UI-managed automations in /config/automations.yaml, reachable per ha-connect. |
HA Automations
Describe in English → write YAML → ha core check → reload → verify.
Home Assistant's failure mode is almost never an error message; it's an
automation that loads fine and silently never does what you meant. The loop
below exists because of that. Assumes the lanes and env from ha-connect,
and entity ids confirmed via ha-context-map, never guessed.
The loop
1. Pin down the English first
"Turn off the TV when nobody's around" hides every real decision: which
entity is the TV, what does "nobody's around" mean (motion silence? for how
long?), what must prevent it (media actively playing?), does it ever turn
back on. Write the trigger / conditions / actions as three English bullets
and get them agreed before YAML. Ambiguity in, dead automation out.
2. Write the YAML
UI-managed automations live in /config/automations.yaml as a list; each
entry needs a unique id: (the UI uses timestamps; any unique string works)
and an alias:.
- id: tv_idle_shutdown
alias: TV idle shutdown
description: Turn off the TV after 2h with no motion in the living areas
triggers:
- trigger: state
entity_id:
- binary_sensor.living_room_motion
- binary_sensor.kitchen_motion
to: "off"
for: "02:00:00"
conditions:
- condition: state
entity_id: media_player.tv
state: "on"
actions:
- action: media_player.turn_off
target:
entity_id: media_player.tv
mode: single
Back up before editing, edit via the pull-down/push-up pattern from
ha-connect (not inline sed over SSH), and know that the entity id HA
mints for the automation slugs from the alias, not the id:
automation.tv_idle_shutdown here, but rename the alias and the entity id
follows on reload.
Test any nontrivial Jinja against live state via POST /api/template
before embedding it (recipe in ha-connect).
3. Check, then reload: never skip, never restart
ssh root@<HA_HOST> 'ha core check'
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" \
-H "Content-Type: application/json" -d '{}' \
"http://$HA_HOST:8123/api/services/automation/reload"
ha core check catches YAML/schema errors; the reload picks up
automations.yaml without a Core restart (a restart drops every for:
timer currently counting and briefly kills the whole house; reserve it for
configuration.yaml changes that actually require it).
4. Verify. The step that isn't optional
A clean reload proves the YAML parsed. It does not prove the automation
exists as you intended, will trigger, or that its actions work. Three
verification tiers, cheapest first:
curl -s -H "Authorization: Bearer $HA_TOKEN" \
"http://$HA_HOST:8123/api/states/automation.tv_idle_shutdown" \
| jq '{state, attributes: {last_triggered: .attributes.last_triggered}}'
curl -s -H "Authorization: Bearer $HA_TOKEN" "http://$HA_HOST:8123/api/states/media_player.tv" | jq .state
curl -s -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
-d '{"entity_id": "automation.tv_idle_shutdown"}' \
"http://$HA_HOST:8123/api/services/automation/trigger"
curl -s -H "Authorization: Bearer $HA_TOKEN" "http://$HA_HOST:8123/api/states/media_player.tv" | jq .state
Tier (b) is the workhorse: read the target entity before, trigger, read it
after, and show both values. "The call returned 200" is not a result;
"on" → "off" is. Note automation.trigger bypasses conditions by default:
it validates the actions, not the logic.
The silent-failure traps
These are the ways an automation lies to you. Check them before declaring
one done, and first when debugging one that "just stopped working".
- Writes can silently no-op. A service call to a wrong-but-plausible
entity id, a
climate.set_temperature in the wrong HVAC mode, a
turn_off on something already off: all return success. The only proof
of a write is re-reading the entity afterwards. Before/after or it didn't
happen.
- A dead service call aborts the rest of the automation. If an action
calls a service that no longer exists (the classic: a
notify.mobile_app_<old_phone> left behind by a replaced phone), the
automation errors out at that step and every later action is skipped,
with nothing visible unless you read the trace or the error log. When an
automation "partially works", look for a dead action above the missing
ones.
- Event-entity attribute triggers go dead after the first event. A state
trigger with
attribute: event_type, to: "pressed" on an event.* entity
only fires when the attribute changes. If the entity has a single event
type (many doorbells), the attribute never changes again and the
automation dies silently after one firing. Trigger on the entity's state
with not_from: ["unknown", "unavailable"] instead: the state is the
last-event timestamp, which changes every event. (Event entities that
clear between detections don't have this problem; know which kind yours
is.)
for: durations reset on any flicker of the watched state, and a Core
restart (not a reload) resets them all. An automation that "never fires"
on a long for: may be getting reset by a chattering sensor; check the
sensor's history.- Guessed entity ids fail quietly.
ha core check does not validate
that entity ids exist. light.livingroom in an action is a runtime
error in a trace you'll never read, not a config error. Ids come from
ha-context-map, verified, or from a live /api/states read.
- Renaming the alias renames the
automation.* entity id, breaking
anything that referenced the old one (dashboards, other automations).
Debugging one that never fires
In order: (1) the automation entity is on (not unavailable; that's an
orphaned registry entry); (2) last_triggered: never, or fired-then-dead?
(3) fired-then-dead on an event entity → the attribute-trigger trap above;
(4) never → verify each trigger entity id exists and check the trace of a
forced condition; (5) fires but actions misbehave → dead-service abort, then
per-action before/after reads.
Traces (Settings → Automations → your automation → Traces) store the last
runs with per-step results; read them before theorizing.
Doctrine
- One automation per concern;
mode: single unless you have a reason.
- Prefer conditions that make firing safe over clever (guard "is it even
on?" rather than trusting the trigger).
- Off-actions are safer than on-actions to automate; be conservative about
automations that turn things on or unlock/open anything.
- Every change ends with a before/after read of the affected entity, pasted,
not asserted.
