haos-blueprints/CLAUDE.md

Home Assistant Automation Blueprints

This repository contains automation blueprints for Home Assistant OS.

Code Review Guidelines

When reviewing or refactoring blueprint files:

1. Code Quality - Improve overall structure and readability
2. Bug Fixes - Identify and fix obvious or critical bugs and mistakes
3. Spelling & Grammar - Correct any spelling or grammatical errors
4. Documentation - Add comments to make the code easier to read and understand
5. User-Friendly Messages - Use entity friendly names instead of entity IDs in notification messages

Versioning

After any change to repository content (blueprints, documentation, or other files), update the version field in manifest.json using semantic versioning:

• Major (X.0.0) - Breaking changes or major new features
• Minor (0.X.0) - New features, enhancements, or significant improvements
• Patch (0.0.X) - Bug fixes, typos, small tweaks, or documentation updates

Repository Structure

Each blueprint is organized in its own folder:

Common/
  Blueprint Name/
    blueprint.yaml    # The automation blueprint
    README.md         # Detailed documentation
Zigbee/
  Blueprint Name/
    blueprint.yaml
    README.md

Working with Blueprints

When modifying a blueprint:

1. Edit blueprint.yaml for code changes
2. Update README.md if the change affects features, configuration, or behavior
3. Keep the blueprint header short (4-5 lines) - detailed docs go in README.md

When creating a new blueprint:

1. Create a new folder named after the blueprint (e.g., Common/My New Blueprint/)
2. Add blueprint.yaml with a short header referencing README.md
3. Add README.md with full documentation (features, how it works, configuration)

Blueprint header format:

# Blueprint Name
# One-line description of what it does.
# See README.md for detailed documentation.
#
# Author: Alexei Dolgolyov (dolgolyov.alexei@gmail.com)

When any blueprint file is moved ask if I need to update the link somewhere else.

Jinja2 Whitespace Issue

Home Assistant evaluates all blueprint variables before conditions are checked. When a variable's Jinja2 template contains whitespace (newlines, indentation), that whitespace gets included in the output even if the template logic produces an empty string.

Problem: Using a variable like {{ my_variable }} in string replacements will include unwanted whitespace.

Solution: Compute complex values inline where they're used, with {%- -%} whitespace control:

# BAD - whitespace from my_list variable will be included
my_list: >
  {% for item in items %}
    {{ item }}
  {% endfor %}

result: "{{ template | replace('{items}', my_list) }}"

# GOOD - inline computation with whitespace control
result: >
  {%- set ns = namespace(items = '') -%}
  {%- for item in items -%}
    {%- set ns.items = ns.items ~ item -%}
  {%- endfor -%}
  {{ template | replace('{items}', ns.items) }}

This pattern is used throughout the Immich Album Watcher blueprint for common_date, common_location, video_warning, and periodic_albums_list.