home-assistant-configuration

Home Assistant configuration work

The consent rules in AGENTS.md apply to everything here: show the change, wait for explicit approval, change nothing else.

Before you write anything

Home Assistant ships a release every month, with new options, deprecations and breaking changes. Training data goes stale fast, so verify syntax against the running version rather than recalling it.

1. get_config — which Home Assistant version is this?
2. get_integration_docs("<integration>") — current YAML syntax and examples.
3. get_breaking_changes — when something stopped working after an update.
4. Read the existing file in full. Every write replaces the whole file.

Frequently-changed areas worth double-checking:

• Template sensors: platform: template under sensor: is deprecated — use the top-level template: key.
• MQTT: platform: mqtt under a domain key is deprecated — use top-level mqtt:.
• Service targeting: entity_id at action level or inside data: is deprecated — use target:.
• Direct state access: states.sensor.x.state is fragile — use states('sensor.x').
• Many integrations moved from YAML to UI-only configuration.

Writing safely

write_config_safe is the sanctioned write path. It validates, backs up, blocks writes that would drop list entries or top-level keys or shrink a file suspiciously, and restores on failure.

1. get_config()                                -> installed version
2. get_integration_docs("template")            -> current syntax
3. read the existing file                      -> ALL of it
4. draft: existing content + your change
5. write_config_safe(path, yaml, dry_run=true) -> pre-validate
6. fix and repeat 5 until clean
7. show the user, wait for approval
8. write_config_safe(path, yaml)               -> write for real

Never write partial content to a config file. Read first, include everything that was already there. write_config_safe blocks the worst cases, but the draft you show the user must already be complete.