Skip to content

claude.md

Latest commit

 

History

History
239 lines (185 loc) · 8.98 KB

claude.md

File metadata and controls

239 lines (185 loc) · 8.98 KB
Raw

Home Assistant Configuration - Complete Reference Index

Last Updated: 2026-06-27 Configuration Status: Production-Ready | Professional Grade

Overview

This Home Assistant configuration is a professional-grade smart home automation system with sophisticated energy management, comprehensive security, and intelligent comfort automation.

Documentation Structure

This documentation has been organized into specialized reference files for easier navigation:

1. System Overview & Architecture

📄 homeassistant-system-overview.md

  • System overview and key statistics
  • Configuration architecture
  • Key areas of focus (Energy, Security, Comfort, Efficiency, Family)
  • Hidden gems and clever solutions
  • Technical excellence assessment

2. Hardware & Infrastructure

📄 homeassistant-hardware-infrastructure.md

  • Network infrastructure (Ubiquiti, Aruba, Zigbee)
  • Power infrastructure (UPS, Shelly, Kasa, SmartThings)
  • ESPHome custom devices (13 devices total)
  • Specialized devices and integrations

3. Energy Management System (Flagship Feature)

📄 homeassistant-energy-management.md

  • Solar & battery infrastructure
  • Energy integrations (Octopus, Predbat, Solar Assistant)
  • Battery mode switching
  • Solar optimization
  • Hot water control
  • EV charging (Zappi)
  • Cost-aware appliance automation

4. Home Systems (Lighting, Climate, Security, Presence)

📄 homeassistant-home-systems.md

  • Lighting system (Hue, LIFX, Innr, Elgato)
  • Climate control (Hive, TRV, Eddi)
  • Security & monitoring (Ring, Reolink, Ubiquiti, Nuki)
  • Presence detection & home modes
  • Smart home connectivity (Alexa, Chromecast, Spotify)
  • Blind & cover automation

5. Notification System & Patterns

📄 homeassistant-notification-patterns.md

  • Notification system architecture
  • Smart quiet hours with keyword exceptions
  • Complete script reference catalog
  • Script decision tree
  • Creating new scripts

6. Automation Patterns & Reference

📄 homeassistant-automation-patterns.md

  • Automation ID uniqueness validation
  • Notable automation patterns (7 key patterns)
  • Real-world examples from configuration
  • Motion detection with context-aware responses
  • Log message best practices

7. Technical Implementation Guide

📄 homeassistant-technical-implementation.md

  • Directory structure (71 package YAML files)
  • Configuration architecture
  • Naming conventions (automations, scripts, helpers, scenes, sensors)
  • Common automation patterns (6 patterns with code)
  • Common script patterns (5 patterns with code)
  • Template patterns
  • Helper entity patterns
  • ESPHome configuration
  • Integration-specific patterns (Octopus, Solar Assistant, Predbat, Ring, Hive, Alexa, Sun-based automations)
  • Recorder & database configuration

8. Best Practices & Development Guide

📄 homeassistant-best-practices-guide.md

  • User preferences & conventions
  • Code review process
  • Common gotchas & best practices
  • Entity ID reference
  • Testing & validation
  • Performance considerations
  • Security considerations
  • Common tasks
  • File maintenance
  • Development workflow

Reference Documentation (in .claude/ folder)

These are comprehensive reference guides for core Home Assistant concepts:

📄 home-assistant-scripts-reference.md Complete guide to Home Assistant scripts including structure, modes, variables, response variables, error handling, and practical patterns.

📄 home-assistant-templating-reference.md Comprehensive Jinja2 templating guide with state access, filters, functions, conditionals, loops, and real-world examples.

📄 home-assistant-splitting-configuration-reference.md Configuration organization guide covering includes, packages, directory structures, and best practices for large systems.

📄 home-assistant-automation-yaml-reference.md Complete automation YAML reference with all trigger types, conditions, actions, modes, and practical examples.

Key Files & Locations

Main Configuration

  • configuration.yaml - Entry point with includes
  • automations.yaml - UI-generated automations (20 total)
  • scripts.yaml - UI-generated scripts
  • scenes.yaml - 3 UI scene definitions; most scenes now live in packages

Package Structure

  • packages/shared_helpers.yaml - Global scripts & templates
  • packages/rooms/ - Room-based packages (living_room, bedroom, kitchen, office, porch, stairs, conservatory, etc.)
  • packages/integrations/ - Integration packages (energy, hvac, messaging, security, transport, weather, infrastructure)

ESPHome Devices

  • esphome/ - 13 custom devices with OTA updates

Quick Navigation by Topic

Energy Management

→ homeassistant-energy-management.md

  • Solar forecasting and battery optimization
  • Rate-aware automation (Octopus Energy)
  • Predbat integration
  • Cost minimization strategies

Motion Detection & Lighting

→ homeassistant-home-systems.md → Lighting System → homeassistant-automation-patterns.md → Motion Detection Patterns

Automation Consolidation

→ homeassistant-automation-patterns.md

  • Trigger ID branching pattern
  • Multi-branch automations
  • Real-world consolidation examples

Script Reference

→ homeassistant-notification-patterns.md → Complete Script Reference

Code Organization

→ homeassistant-technical-implementation.md → Configuration Architecture → homeassistant-technical-implementation.md → Naming Conventions

Development Workflow

→ homeassistant-best-practices-guide.md → Development Workflow → homeassistant-best-practices-guide.md → Code Review Process

Session Work Summary (2026-01-22)

Phases 1-4 Complete:

  • ✅ Phase 1: Helper scripts and templates (64beb615)
  • ✅ Phase 2.1: Replace clock/log patterns (ce557e52)
  • ✅ Phase 2.2: Consolidate fridge/freezer automations (14335470)
  • ✅ Phase 3: Consolidate stairs motion detection (375c8754)
  • ✅ Phase 4.1: Porch motion consolidation (26603d94)
  • ✅ Phase 4.2: Kitchen motion consolidation (eab1014f)
  • ⏳ Phase 4.3: Stairs additional consolidation (pending)

Critical Fixes Applied:

  • Fixed log_with_clock script (response_variables syntax and template access)
  • Consolidated 8 kitchen automations into 3
  • Consolidated 2 porch automations into 1
  • Added missing scene definitions

Session Statistics:

  • 9 commits across 4 optimization phases
  • 34 total fixes across 12 room packages
  • 5,500+ lines of YAML reviewed and validated
  • 0 critical issues remaining in validated packages

Quick Reference

Most Important Concepts

  1. Response Variables - Always use response_variables: (plural) in scripts
  2. Trigger IDs - Use for branching instead of multiple automations
  3. First Match Wins - Order matters in choose blocks
  4. Template Safety - Always use | default() for undefined values
  5. Parallel Actions - For independent operations only
  6. Logging - Append to messages, don't replace
  7. Automation Modes - Choose queued for motion, single for time-based

Critical Rules

  • ❌ Never use singular response_variable: - always plural response_variables:
  • ❌ Never use condition: service: - use action: domain.service
  • ❌ Never add Claude attribution to commits - user-attributed only
  • ✅ Always validate automation IDs are unique (13-digit numbers)
  • ✅ Always use | float(0) for sensor comparisons
  • ✅ Always include logging in automations

Common Commands

# Validate configuration
Configuration → Settings → System → Check Configuration

# View automation traces
Automations & Scenes → Click automation → Traces tab

# Test templates
Developer Tools → Template

# Check entity states
Developer Tools → States

Getting Help

For specific questions, refer to:

  • How do I write a script? → home-assistant-scripts-reference.md
  • How do I write a template? → home-assistant-templating-reference.md
  • How do I consolidate automations? → homeassistant-automation-patterns.md
  • What naming convention should I use? → homeassistant-technical-implementation.md
  • How do I organize my configuration? → home-assistant-splitting-configuration-reference.md
  • What best practices should I follow? → homeassistant-best-practices-guide.md

Archive

The original claude.md file (2,332 lines) has been split into focused reference documents for better navigation and maintenance.