A comprehensive system for managing Home Assistant configurations with automated validation, testing, and deployment - all enhanced by Claude Code for natural language automation creation.

Click to play

• 🤖 AI-Powered Automation Creation: Use Claude Code to write automations in plain English
• 🛡️ Multi-Layer Validation: Comprehensive validation prevents broken configurations
• 🔄 Safe Deployments: Pre-push validation blocks invalid configs from reaching HA
• 🔍 Entity Discovery: Advanced tools to explore and search available entities
• ⚡ Automated Hooks: Validation runs automatically on file changes
• 📊 Entity Registry Integration: Real-time validation against your actual HA setup

New to command line tools? No problem! We've made it super easy to get started.

Download the project and run the setup script for your operating system:

1. Download or clone this repository (quick tutorial)
2. Open Terminal and navigate to the project folder (how to use Terminal on Mac)
3. Run the setup script:

./setup-mac.sh

1. Download or clone this repository (quick tutorial)
2. Open Command Prompt and navigate to the project folder (how to use terminal on Win)
3. Run the setup script:

setup-windows.bat

• ✅ Check that you have all required software (Python, Git, etc.)
• ✅ Download and install Claude Code automatically if missing
• ✅ Install any missing dependencies automatically
• ✅ Set up the Python environment with all needed packages
• ✅ Guide you through the next steps

1. Configure your Home Assistant connection (the script will show you how)
2. Open Claude Code (download here if not installed) and navigate to your project folder
3. Pull your configuration by typing make pull in Claude Code
4. Start creating automations with Claude Code!

That's it! The scripts handle all the technical setup for you. Claude Code makes running commands super easy - just type them directly!

This repository provides a complete framework for managing Home Assistant configurations with Claude Code. Here's how it works:

• Template Configs: The config/ folder contains sanitized example configurations (no secrets)
• Validation Tools: The tools/ folder has all validation scripts
• Management Commands: The Makefile contains pull/push commands
• Development Setup: pyproject.toml and other dev files for tooling

git clone [email protected]:philippb/claude-homeassistant.git
cd claude-homeassistant
make setup  # Creates Python venv and installs dependencies

Copy the example environment file and configure your settings:

cp .env.example .env
# Edit .env with your actual Home Assistant details

The .env file should contain:

# Home Assistant Configuration
HA_TOKEN=your_home_assistant_token
HA_URL=http://your_homeassistant_host:8123

# SSH Configuration for rsync operations
HA_HOST=your_homeassistant_host
HA_REMOTE_PATH=/config/

# Local Configuration (optional - defaults provided)
LOCAL_CONFIG_PATH=config/
BACKUP_DIR=backups
VENV_PATH=venv
TOOLS_PATH=tools

Required: Install the Advanced SSH & Web Terminal add-on for Home Assistant, which provides SSH/SFTP access needed for the rsync operations in this project.

# Generate a new SSH key pair for Home Assistant
ssh-keygen -t ed25519 -f ~/.ssh/homeassistant -C "[email protected]"

# Verify the key files were created
ls -l ~/.ssh/homeassistant*

username: root
password: ""
authorized_keys:
  - >-
    ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... [email protected]
sftp: true
compatibility_mode: false
allow_agent_forwarding: false
allow_remote_port_forwarding: false
allow_tcp_forwarding: false

# Home Assistant SSH Configuration
Host homeassistant
  HostName homeassistant.local  # or your HA IP address
  User root
  IdentityFile ~/.ssh/homeassistant
  StrictHostKeyChecking no

# Test the SSH connection
ssh homeassistant

# You should see:
# Welcome to the Home Assistant command line.

To get your HA_TOKEN:

1. Go to Home Assistant → Settings → People → Your Profile
2. Scroll to "Long-lived access tokens"
3. Click "Create Token"
4. Give it a name like "Claude Home Assistant"
5. Copy the token and paste it as HA_TOKEN value in your .env file

make pull  # Downloads YOUR actual HA config, overwriting template files

Important: This step replaces the template config/ folder with your real Home Assistant configuration files.

• Edit your real configs locally with full validation
• Use Claude Code to create automations in natural language
• Validation hooks automatically check syntax and entity references

make push  # Uploads changes back to your HA instance (with validation)

1. Template Start: You begin with example configs showing proper structure
2. Real Data: First make pull overwrites templates with your actual HA setup
3. Local Development: Edit real configs locally with validation safety
4. Safe Deployment: make push validates before uploading to prevent broken configs

This gives you a complete development environment while only modifying your HA instance when completed.

This project uses make commands for configuration management. If you don't have make installed:

macOS:

xcode-select --install  # Installs Command Line Tools including make

Windows:

• Option 1: Use WSL (Windows Subsystem for Linux) - recommended
• Option 2: Install via Chocolatey: choco install make
• Option 3: Use Git Bash (includes make)
• Option 4: Install MinGW-w64

Alternative: If you can't install make, you can run the underlying commands directly by checking the Makefile for the actual command syntax.

├── config/                 # Home Assistant configuration files, downloaded from HA via script
│   ├── configuration.yaml
│   ├── automations.yaml
│   ├── scripts.yaml
│   └── .storage/          # Entity registry (pulled from HA)
├── tools/                 # Validation scripts for Claude
│   ├── run_tests.py       # Main test suite runner
│   ├── yaml_validator.py  # YAML syntax validation
│   ├── reference_validator.py # Entity reference validation
│   ├── ha_official_validator.py # Official HA validation
│   └── entity_explorer.py # Entity discovery tool
├── .claude-code/          # Claude Code project settings
│   ├── hooks/            # Automated validation hooks
│   └── settings.json     # Project configuration
├── .env.example          # Environment configuration template
├── venv/                 # Python virtual environment
├── Makefile              # Management commands
└── CLAUDE.md             # Claude Code instructions

make pull      # Pull latest config from Home Assistant
make push      # Push local config to HA (with validation)
make backup    # Create timestamped backup
make validate  # Run all validation tests

make entities                           # Show entity summary
make entities ARGS='--domain climate'   # Climate entities only
make entities ARGS='--search motion'    # Search for motion sensors
make entities ARGS='--area kitchen'     # Kitchen entities only
make entities ARGS='--full'            # Complete detailed output

. venv/bin/activate
python tools/yaml_validator.py         # YAML syntax only
python tools/reference_validator.py    # Entity references only
python tools/ha_official_validator.py  # Official HA validation

The system provides three layers of validation:

• Validates YAML syntax with HA-specific tags (!include, !secret, !input)
• Checks file encoding (UTF-8 required)
• Validates basic HA file structures

• Verifies all entity references exist in your HA instance
• Checks device and area references
• Warns about disabled entities
• Extracts entities from Jinja2 templates

• Uses Home Assistant's own validation tools
• Most comprehensive check available
• Catches integration-specific issues

Two hooks ensure configuration safety:

1. Post-Edit Hook: Runs validation after editing YAML files
2. Pre-Push Hook: Validates before syncing to HA (blocks if invalid)

This system supports standardized entity naming:

Format: location_room_device_sensor

Examples:

binary_sensor.home_basement_motion_battery
media_player.office_kitchen_sonos
climate.home_living_room_heatpump

With Claude Code, you can:

1. Describe automations in English:

   "Turn off all lights at midnight on weekdays"
   

2. Claude writes the YAML:

   - id: weekday_midnight_lights_off
     alias: "Weekday Midnight Lights Off"
     trigger:
       - platform: time
         at: "00:00:00"
     condition:
       - condition: time
         weekday: [mon, tue, wed, thu, fri]
     action:
       - service: light.turn_off
         target:
           entity_id: all

3. Automatic validation ensures correctness

4. Deploy safely with make push

The entity explorer helps you understand what's available:

# Find all motion sensors
. venv/bin/activate && python tools/entity_explorer.py --search motion

# Show all climate controls
. venv/bin/activate && python tools/entity_explorer.py --domain climate

# Kitchen devices only
. venv/bin/activate && python tools/entity_explorer.py --area kitchen

• Secrets Management: secrets.yaml is excluded from validation
• SSH Authentication: Uses SSH keys for secure HA access
• No Credentials Stored: Repository contains no sensitive data
• Pre-Push Validation: Prevents broken configs from reaching HA
• Backup System: Automatic timestamped backups before changes

1. Check YAML syntax first: . venv/bin/activate && python tools/yaml_validator.py
2. Verify entity references: . venv/bin/activate && python tools/reference_validator.py
3. Check HA logs if official validation fails

# 1. Check SSH key files exist and have correct permissions
ls -la ~/.ssh/homeassistant*

# 2. Check SSH config
grep -A 5 "Host homeassistant" ~/.ssh/config

# 3. Test SSH connection
ssh homeassistant "ls /config"

# 4. Test rsync (what make pull/push uses)
rsync -avz --dry-run homeassistant:/config/ ./test/

. venv/bin/activate
pip install homeassistant voluptuous pyyaml jsonschema requests

Configure via .env file in project root (copy from .env.example):

cp .env.example .env

Available variables:

# Home Assistant Configuration
HA_TOKEN=your_home_assistant_token       # HA API token
HA_URL=http://your_homeassistant_host:8123  # HA instance URL

# SSH Configuration for rsync operations
HA_HOST=your_homeassistant_host          # SSH hostname for HA
HA_REMOTE_PATH=/config/                  # Remote config path

# Local Configuration (optional - defaults provided)
LOCAL_CONFIG_PATH=config/                # Local config directory
BACKUP_DIR=backups                       # Backup directory
VENV_PATH=venv                          # Python virtual environment path
TOOLS_PATH=tools                        # Tools directory

Located in .claude-code/settings.json:

{
  "hooks": {
    "enabled": true,
    "posttooluse": [".claude-code/hooks/posttooluse-ha-validation.sh"],
    "pretooluse": [".claude-code/hooks/pretooluse-ha-push-validation.sh"]
  },
  "validation": {
    "enabled": true,
    "auto_run": true,
    "block_invalid_push": true
  }
}

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all validations pass
5. Submit a pull request

Apache 2.0

• Home Assistant for the amazing platform
• Claude Code for AI-powered development
• The HA community for validation best practices

Ready to revolutionize your Home Assistant automation workflow? Start by describing what you want in plain English and let Claude Code handle the rest! 🚀