home-assistant-blueprints/CLAUDE.md

CLAUDE.md

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

Repository Overview

This is a Home Assistant blueprints repository containing automation blueprints for Home Assistant. The repository follows a simple structure with individual YAML blueprint files in the root directory alongside comprehensive documentation.

Architecture

Blueprint Structure

• Blueprint files: YAML files defining Home Assistant automation blueprints
• Documentation: README.md provides detailed usage examples and configuration guidance
• Each blueprint is self-contained with embedded metadata (name, description, domain, inputs)

Current Blueprints

Multi-Press Action Blueprint (multi_press_action.yaml)

• Purpose: Trigger different actions based on rapid entity state changes (single, double, triple, quad press)
• Key features:
  • Configurable time window for press detection
  • Immediate vs delayed single-press modes
  • Support for complex action sequences with conditions
• Architecture patterns:
  • Uses Home Assistant blueprint format with input selectors
  • Implements state machine logic with press counting
  • Uses mode: restart to handle overlapping triggers
  • Template-based conditional logic for press count evaluation

Development Workflow

Adding New Blueprints

1. Create new .yaml file in repository root
2. Follow Home Assistant blueprint format:
   • blueprint: section with metadata
   • input: section with user-configurable parameters
   • trigger: and action: sections for automation logic
3. Update README.md with new blueprint documentation
4. Test blueprint by importing into Home Assistant development environment

Blueprint Best Practices

• Use descriptive names and clear descriptions for inputs
• Provide sensible defaults for optional parameters
• Include comprehensive selector types for user inputs
• Use mode: restart or mode: single appropriately based on use case
• Implement proper variable scoping within actions
• Include detailed documentation with usage examples

Testing

• No automated testing framework (blueprints are tested in Home Assistant directly)
• Manual testing involves:
  1. Importing blueprint into Home Assistant
  2. Creating automation from blueprint
  3. Testing various input combinations and edge cases
  4. Verifying automation traces for debugging

Import URLs

• Repository uses custom Git hosting at git.johnogle.info
• Import URL pattern: https://git.johnogle.info/johno/home-assistant-blueprints/raw/branch/main/{blueprint_name}.yaml

File Organization

/
├── README.md                    # Comprehensive documentation
├── multi_press_action.yaml     # Multi-press detection blueprint
└── CLAUDE.md                   # This file

Home Assistant Blueprint Conventions

Input Types

• entity: Entity selector for picking Home Assistant entities
• action: Action sequence selector for automation actions
• number: Numeric input with min/max/step validation
• boolean: True/false toggle
• text: String input fields

Template Usage

• Use !input to reference blueprint inputs
• Template conditions with {{ }} syntax for dynamic logic
• Variable assignment and reference within action sequences

Automation Modes

• restart: Stops current execution and restarts on new trigger
• single: Ignores new triggers while running
• parallel: Allows multiple simultaneous executions