homeassistant-claude-kit

A fully custom Home Assistant setup -- automation templates, mobile-first React dashboard, and AI-guided configuration -- built and managed entirely through Claude Code.

Home  ·  Climate zones  ·  Energy & EV charging  ·  Security cameras

Why This Exists

The problem with Lovelace. It's great for quick device control, but its card model is centered around individual devices and rooms. Real home automation is more nuanced -- you don't control a boiler directly, you set a heating schedule with climate zones that don't always map 1:1 to rooms (an open-plan ground floor is one zone, not four). You want manual overrides per zone when needed, but the system should coordinate the boiler with the TRVs automatically, driven by temperature sensors. When there's spare solar power, the ACs should heat opportunistically -- again with manual override when you want it. Lovelace doesn't give you this level of control over the interface or the logic behind it.

What made it possible. This entire system -- 70+ automations, a custom React dashboard, validation tooling, entity management -- was built from scratch in two weeks by one person using Claude Code. There is no visual editor for the dashboard; it's custom React code. There is no UI for editing automations; everything lives in YAML files managed through Claude Code. You describe what you want in plain language, and the AI writes the code, validates it, deploys it, and documents it. Yes, there are risks in AI-generated code, but they are mitigated by validation at every step (pre-push hooks, TypeScript checks, entity reference validation), a structured workflow that catches issues early (Compound Engineering), and tight integration with HA through CLI tools that eliminate manual copy-paste and command-running.

The result outweighs the risks by far: a system that would have taken months to build manually, working exactly the way you want it, fully documented, and continuously improvable through the same AI workflow that built it.

Design Principles

• Use-case driven, not device-driven. The dashboard and automations are organized around how you use your home -- climate zones, activity modes, energy management -- not around individual devices or integrations.
• Nothing hardcoded. Every threshold, timeout, temperature, brightness, and duration is an input_* helper, visible and editable in the Settings view. Automations read these at runtime -- no magic numbers, everything tweakable without touching YAML.
• Self-documenting. docs/system-*.md describes what IS (hardware, entities, design decisions -- generated during setup, populated as you build). docs/solutions/ captures debugging lessons (34 docs and growing). Both are updated as part of every change, so documentation never drifts from reality.
• Mobile-first. The dashboard is designed for phones. Every interaction is touch-optimized. When a design compromise was needed, mobile experience was favored over desktop.
• Validate before deploy. Hooks run on every file edit. make push validates before syncing. Broken configs never reach HA.
• Event-driven, not polling. Automations use state triggers with for: durations, not timers or delays. The system reacts to changes rather than checking on intervals.

Quick Start

You'll need: SSH access to HA, a long-lived token, Python 3.12+, rsync -- see SETUP.md for details.

git clone https://github.com/dcb/homeassistant-claude-kit
cd homeassistant-claude-kit
cp .env.example .env   # Fill in HA_HOST, HA_URL, HA_TOKEN, SSH_USER
make setup             # Python venv + dependencies

Privacy: Claude Code reads your config files to help you. This includes entity IDs, room names, and automation logic. See PRIVACY.md for details and how to enable privacy mode.

Then open Claude Code in the repo and say "set up my home". That's it -- Claude handles the rest.

New here? SETUP.md (prerequisites) --> PROMPTING-GUIDE.md (how to use)

Table of Contents

• Why This Exists
• Design Principles
• Quick Start
• How to Use This Kit
• What's Included
• Project Structure
• Available Commands
• Architecture
• Acknowledgments

How to Use This Kit

Just talk to Claude (most users) -- Describe what you want in plain language. Claude reads the project's CLAUDE.md automatically and knows the entity naming conventions, validation rules, and deployment workflow. See the Prompting Guide for examples from simple tasks to complex automations.

Learn the patterns (power users) -- For complex features, use the Compound Engineering workflow: /ce:brainstorm to explore what to build, /ce:plan to design it, /ce:work to implement, /ce:compound to document the solution. Review docs/solutions/ for known anti-patterns before starting. Read docs/system-*.md for your domain before modifying automations.

Do it yourself (manual) -- All make commands and YAML templates are documented. You can edit files directly, validate with make validate, and deploy with make push. Initial entity discovery and dashboard config generation are easier with Claude Code, but everything else works without it.

What's Included

Automation Templates

Templates in docs/templates/config/ -- copied and customized during setup.

Dashboard

React 19 + TypeScript + Tailwind v4, deployed as an HA panel_custom via make deploy-dashboard.

Room controls  ·  AC popup  ·  TV remote  ·  Settings (every value is configurable)

• Room cards with temperature, humidity, motion, light status
• Bottom-sheet popups with light sliders, climate controls, media players
• Camera streams (MSE on desktop, WebRTC on mobile/iOS) with snapshot history
• EV charger card with solar/fast/manual modes and charging cost breakdown
• Unified control system with 4-phase state machine: debounce, inflight tracking, post-confirmation hold

See dashboard/CLAUDE.md for the full development guide.

Tip: Make the dashboard your default view HA always opens to a Lovelace dashboard by default. To land on the custom panel instead, install Custom Sidebar via HACS, add it to frontend.extra_module_url, and create custom-sidebar-config.yaml with default_path: /custom-dashboard. See Step 10 in the Setup Guide for details.

Health Monitoring & Charts

Boiler diagnostics & heating timeline  ·  Solar production with charging breakdown

• Heating timeline showing boiler and per-zone activity over the day
• Per-zone temperature charts with target lines and TRV calibration offsets
• Solar production chart with house/charger/forecast overlays and daily cost breakdown
• Integration health status with watchdog retry history

Validation Tools

make validate   # Runs all three layers:
                # 1. YAML syntax validation
                # 2. Entity reference checking
                # 3. Official HA configuration validation

Pre-push hooks block broken configs automatically. Template placeholder IDs (your_*) are skipped.

Entity Rename Skill

Batch rename HA entities to follow a consistent domain.{room}_{descriptor} convention:

entity-rename   # Discover → propose → approve → execute → verify

Uses ha-ws (WebSocket API via SSH) for renames, then updates all YAML and TypeScript references automatically. Tracks every rename in entity-renames.json for rollback safety.

Institutional Knowledge

34 solution docs in docs/solutions/ covering common HA pitfalls: Jinja2 scoping bugs, watchdog patterns, automation mode traps, dashboard timing issues, API gotchas, and more. These are automatically surfaced by the planning workflow to prevent repeating past mistakes.

Project Structure

config/                    # HA config files (synced via rsync)
  automations/             # Split automation files by domain
  scripts/                 # Split script files
  configuration.yaml       # Main config + input helpers
dashboard/                 # React 19 custom panel
  src/components/          # Cards, controls, popups, layout
  src/hooks/               # useHistory, useWeatherForecast, useGo2RtcStream
  src/lib/                 # entities.ts, areas.ts, control hooks
  src/views/               # Home, Climate, Energy, Security, Settings, Health
docs/
  templates/config/        # Automation YAML templates
  solutions/               # 34 debugging lessons and patterns
  system-*.md              # System documentation (always current)
  brainstorms/             # Feature exploration documents
  plans/                   # Implementation plans
tools/                     # Validation and entity management scripts
.claude/
  skills/                  # AI skills (setup-infrastructure, setup-customize, entity-rename)
  hooks/                   # Pre/post tool-use validation hooks
Makefile                   # pull, push, validate, deploy-dashboard

Available Commands

Architecture

Configuration flows through an rsync-based pipeline:

1. Edit locally -- YAML files in config/, React components in dashboard/
2. Validate -- hooks run on every file edit (YAML syntax, entity refs, TypeScript)
3. Push -- make push syncs to HA via rsync over SSH (.storage/ is protected)
4. Reload -- automations, scripts, and templates reload without HA restart

The dashboard is a standalone React app served as a panel_custom iframe. It connects to HA via WebSocket (embedded auth when in HA, token auth in dev mode).

Updating

The kit is versioned (see CHANGELOG.md). To pull later fixes and features into an install that has diverged from the template, run the upgrade skill in Claude Code:

"upgrade the kit"

It reads the structured changelog (kit-changelog.yaml), works out which changes are still relevant to your install, and applies them on a branch — rather than a blind git pull/merge that would fight your customizations. Your install-specific files stay untracked and out of its way: config/ (your real HA config), .env / dashboard/.env.local (credentials), and setup-state.json. The dashboard's entities.ts / areas.ts ship as scaffolds and are generated for your home by setup-customize.

Manual fallback (advanced): the kit's tracked files can be updated with git pull from the kit remote, then cd dashboard && npm install && npm run build && cd .. && make deploy-dashboard. Prefer the upgrade skill — it handles divergence and won't clobber your generated entities.ts/`ar