blueprints/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Home Assistant Blueprints repository containing reusable automation templates for smart home systems. All blueprints are YAML configuration files that can be imported directly into Home Assistant.

Common Development Tasks

Deployment

After committing and pushing changes, deploy blueprints to Home Assistant:

labctl blueprints:pull ha      # from the lab repo; runs git pull in the checkout on the ha volume

Then reload automations in the Home Assistant UI (Developer tools → YAML → Automations) so blueprint changes take effect.

Testing & Validation

• Blueprint Validation: Use Home Assistant's built-in blueprint importer to validate YAML syntax
• Template Testing: Test Jinja2 templates in Home Assistant Developer Tools → Template tab
• Live Testing: Import blueprint into Home Assistant and create test automation to verify behavior

Working with Blueprints

When modifying or creating blueprints:

1. Follow the standard Home Assistant blueprint schema structure
2. Always include comprehensive descriptions for user clarity
3. Provide sensible defaults for all input parameters
4. Use proper selectors for entity inputs (entity, device, area selectors)
5. Test templates for edge cases (unavailable entities, null states)

Architecture & Code Structure

Blueprint Components

Every blueprint follows this structure:

• blueprint: Metadata section with name, description, domain (always "automation")
• input: User-configurable parameters with selectors and defaults
• trigger: Event triggers (state changes, time patterns, device events)
• condition: Optional conditional logic
• variables: Template variables for complex logic
• action: Automation actions to execute
• mode: Execution mode (single, restart, queued, parallel)

Key Patterns

Template Safety

Always use fallback defaults in templates:

{{ states('sensor.temperature') | float(0) }}
{{ state_attr('device.battery', 'battery_level') | int(100) }}

Entity Expansion

Use expand() for working with entity groups:

{% for entity_id in expand(battery_sensors) | map(attribute='entity_id') | list %}

Z-Wave Event Handling

Z-Wave central scene events follow this pattern:

trigger:
  - platform: event
    event_type: zwave_js_value_notification
    event_data:
      command_class: 91  # Central Scene
      property_key: "001"  # Scene ID

Complex State Calculations

Use namespace objects for accumulating values:

{% set ns = namespace(total=0, count=0) %}
{% for entity in entities %}
  {% set ns.total = ns.total + states(entity) | float(0) %}
  {% set ns.count = ns.count + 1 %}
{% endfor %}

Blueprint Categories

HVAC & Climate Control

• hvac-failure-monitor.yaml: Monitors HVAC performance using temperature differentials
• fan-management.yaml: Bathroom fan automation with light triggers
• fan-cadence.yaml: Periodic fan cycling with override protection

Power & Energy

• power-monitoring.yaml: Detects power spikes for appliance identification
• battery-monitor.yaml: Multi-device battery level monitoring

Smart Switches & Scenes

• multi-tap-automation.yaml: Z-Wave switch multi-tap scene control
• multi-tap-automation-homeseer-and-zooz.yaml: Enhanced multi-tap with HomeSeer/Zooz support
• indication.yaml: HomeSeer WD200+ LED indicator control

Security & Utility

• simulated-presence.yaml: Random light automation for security
• state-opposite.yaml: Bidirectional entity state synchronization

Important Implementation Notes

Input Validation

• Use proper selector types (number with min/max, boolean, entity with domain filter)
• Always provide defaults to prevent undefined errors
• Use multi-select for flexibility where appropriate

Error Handling

• Check entity availability before actions
• Use conditional sequences for optional actions
• Implement proper fallbacks for missing data

Performance Considerations

• Use appropriate automation modes (single for exclusive, restart for updates)
• Minimize template complexity in frequently-triggered automations
• Consider using time patterns instead of constant state monitoring

Common Issues & Solutions

• Template errors: Test in Developer Tools first
• Entity unavailable: Add availability checks in conditions
• Z-Wave events not firing: Verify device supports Central Scene command class
• HVAC monitoring false positives: Adjust temperature thresholds and time windows
• always push after commit