Add entity name as comment after numeric ID in YAML configuration

[leclerck2001]

Problem Description

Since Home Assistant version 2025.6, YAML configuration files have moved away from using human-readable entity IDs in favor of numeric references. While this change may have technical benefits, it has significantly impacted the maintainability and readability of YAML configuration files for users who manually edit and maintain their configurations.

Current Issues:

• YAML configuration files are no longer human-readable when they contain numeric entity references
• Troubleshooting automations and scripts becomes much more difficult without recognizable entity names
• Code review and collaboration on configurations is severely hampered
• New users and experienced users alike struggle to understand what entities are being referenced
• Manual documentation of configurations requires significant additional effort
• Version control diffs become meaningless when only numeric IDs are shown

Impact on User Experience:

• Increased time spent identifying entities during configuration maintenance
• Higher barrier to entry for users learning YAML configuration
• Reduced ability to quickly spot errors or understand automation logic
• Loss of self-documenting code benefits that readable entity IDs provided

Proposed Solution

Automatically append human-readable entity name comments immediately after numeric entity references in YAML configuration files.

Implementation Details:

1. Automatic Comment Generation: When Home Assistant writes or updates YAML files containing numeric entity references, automatically append a comment with the entity’s friendly name and/or entity ID.
2. Comment Format: Use a standardized, consistent format that doesn’t interfere with YAML parsing but provides maximum readability.
3. Dynamic Updates: Comments should be automatically updated when entity names change, ensuring they remain accurate.
4. Optional Feature: Provide a configuration option to enable/disable this feature for users who prefer minimal YAML files.

Benefits:

• Maintains backward compatibility while improving readability
• Requires no user intervention - works automatically
• Preserves the technical benefits of numeric references
• Significantly improves code maintainability and debugging
• Reduces learning curve for YAML configuration
• Enables better collaboration and version control practices

Configuration Option:

yaml
add the description of the device (home-assistant-voice-098dfb) after the ID.

  actions:
  - action: media_player.play_media
    target:
      device_id:
      - 3d746d8c5086e6a6fe734c7bfb530867 #home-assistant-voice-098dfb```

This feature would bridge the gap between technical efficiency and human usability, making Home Assistant configurations both robust and maintainable.

[Didgeridrew]

@leclerck2001

Since Home Assistant version 2025.6, YAML configuration files have moved away from using human-readable entity IDs in favor of numeric references

This has been the case for Device-based triggers, conditions, and actions since they were introduced. If you want the entity ID in plain text use Entity-based components.

Why and how to avoid device_ids in automations and scripts

Background When you start writing automations, a device trigger seems the obvious choice. Everybody knows what a device is and it comes at the top of the UI dropdown list. [image] It works… but it is certainly not a “great way to start” because it is storing up problems for the future. Far better to use an entity, with state or numeric_state. This topic is part of the community-driven cookbook where you can find other topics you might be interested in or might like to contribute to. Devi…

@leclerck2001

Automatic Comment Generation: When Home Assistant writes or updates YAML files containing numeric entity references, automatically append a comment with the entity’s friendly name and/or entity ID.

Everything you see in the UI is serialized as JSON, which does not support comments.

There are multiple threads about this kind of thing ( 1, 2, 3 )

Comments are supported if you just use pure YAML, but the trade off is that you can’t use the UI editors.

[123 (Taras)]

@leclerck2001

Since Home Assistant version 2025.6, YAML configuration files have moved away from using human-readable entity IDs in favor of numeric references

Using the Automation Editor in 2025.6, I created an automation with a State Trigger. I selected a binary_sensor and the value of its entity_id, when viewed in YAML mode, is a human-readable string (binary_sensor.rpi_power_status), not a “numeric reference”.

Please explain what steps you performed to produce an entity_id containing a “numeric reference”.

[Sir_Goodenough ((SG) WhatAreWeFixing.Today)]

Hello leclerck2001,

I have not tested all cases, but I have been told that the entity numeric ID thing from the world of device_id is supposed to work wherever the entity words would in the world of entity_id. Give it some testing…
If so you don’t need the name id you have the number id, just use the number.
Personally I don’t use the device_id crap any more than I have to because I’m not the intended user (computers are).