Skip to content
Back to search

homeassistant-claude-kit

SkillWorks with Claude CodeGitHub

AI-guided Home Assistant setup — automation templates, mobile-first React dashboard, and Claude Code skills for configuration management

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dcb--homeassistant-claude-kit/badge.svg)](/listings/dcb--homeassistant-claude-kit)

HTML

<a href="/listings/dcb--homeassistant-claude-kit"><img src="/api/listings/dcb--homeassistant-claude-kit/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **You'll need:** SSH access to HA, a long-lived token, Python 3.12+, rsync -- see [SETUP.md](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](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](SETUP.md) (prerequisites) --> [PROMPTING-GUIDE.md](PROMPTING-GUIDE.md) (how to use)

| You do (once) | The kit handles (always) | |---------------|------------------------| | Install SSH add-on + create token | Validate before every push | | Fill in `.env` | Discover entities from HA registries | | Open Claude Code, say "set up my home" | Generate dashboard + automation config |

<details> <summary>Table of Contents</summary>

- [Why This Exists](#why-this-exists) - [Design Principles](#design-principles) - [Quick Start](#quick-start) - [How to Use This Kit](#how-to-use-this-kit) - [What's Included](#whats-included) - [Project Structure](#project-structure) - [Available Commands](#available-commands) - [Architecture](#architecture) - [Acknowledgments](#acknowledgments)

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 261 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # homeassistant-claude-kit
  2. A fully custom Home Assistant setup -- automation templates, mobile-first React dashboard, and AI-guided configuration -- built and managed entirely through Claude Code.
  3. <p align="center">
  4. <img src="docs/images/home.png" width="195" alt="Home -- room cards, weather, modes, media">
  5. <img src="docs/images/climate.png" width="195" alt="Climate -- zone cards with temperature charts">
  6. <img src="docs/images/energy.png" width="195" alt="Energy -- power flow, EV charger, solar priority">
  7. <img src="docs/images/security.png" width="195" alt="Security -- camera grid with battery badges">
  8. </p>
  9. <p align="center"><em>Home &nbsp;·&nbsp; Climate zones &nbsp;·&nbsp; Energy &amp; EV charging &nbsp;·&nbsp; Security cameras</em></p>
  10. ## Why This Exists
  11. **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.
  12. **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](https://claude.com/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](PROMPTING-GUIDE.md#6-compound-engineering-workflow)), and tight integration with HA through CLI tools that eliminate manual copy-paste and command-running.
  13. 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.
  14. ## Design Principles
  15. - **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.
  16. - **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.
  17. - **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.
  18. - **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.
  19. - **Validate before deploy.** Hooks run on every file edit. `make push` validates before syncing. Broken configs never reach HA.
  20. - **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.
  21. ## Quick Start
  22. > **You'll need:** SSH access to HA, a long-lived token, Python 3.12+, rsync -- see [SETUP.md](SETUP.md) for details.
  23. ```bash
  24. git clone https://github.com/dcb/homeassistant-claude-kit
  25. cd homeassistant-claude-kit
  26. cp .env.example .env # Fill in HA_HOST, HA_URL, HA_TOKEN, SSH_USER
  27. make setup # Python venv + dependencies
  28. ```
  29. > **Privacy:** Claude Code reads your config files to help you. This includes entity IDs,
  30. > room names, and automation logic. See [PRIVACY.md](PRIVACY.md) for details and how to
  31. > enable privacy mode.
  32. Then open Claude Code in the repo and say **"set up my home"**. That's it -- Claude handles the rest.
  33. **New here?** [SETUP.md](SETUP.md) (prerequisites) --> [PROMPTING-GUIDE.md](PROMPTING-GUIDE.md) (how to use)
  34. | You do (once) | The kit handles (always) |
  35. |---------------|------------------------|
  36. | Install SSH add-on + create token | Validate before every push |
  37. | Fill in `.env` | Discover entities from HA registries |
  38. | Open Claude Code, say "set up my home" | Generate dashboard + automation config |
  39. <details>
  40. <summary>Table of Contents</summary>
  41. - [Why This Exists](#why-this-exists)
  42. - [Design Principles](#design-principles)
  43. - [Quick Start](#quick-start)
  44. - [How to Use This Kit](#how-to-use-this-kit)
  45. - [What's Included](#whats-included)
  46. - [Project Structure](#project-structure)
  47. - [Available Commands](#available-commands)
  48. - [Architecture](#architecture)
  49. - [Acknowledgments](#acknowledgments)
  50. </details>
  51. ## How to Use This Kit
  52. **Just talk to Claude** (most users) -- Describe what you want in plain language. Claude reads the project's [CLAUDE.md](CLAUDE.md) automatically and knows the entity naming conventions, validation rules, and deployment workflow. See the **[Prompting Guide](PROMPTING-GUIDE.md)** for examples from simple tasks to complex automations.
  53. **Learn the patterns** (power users) -- For complex features, use the [Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin) 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.
  54. **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.
  55. ## What's Included
  56. ### Automation Templates
  57. Templates in `docs/templates/config/` -- copied and customized during setup.
  58. | Domain | File | What It Does |
  59. |--------|------|-------------|
  60. | Climate | `climate.yaml` | TRV zone control, adaptive preheat, day/night schedules |
  61. | Energy | `energy.yaml` | Solar EV charging feedback loop, overnight decisions, session summaries |
  62. | Lighting | `lighting.yaml` | Motion lights with AL integration, movie/night/work modes, porch twilight |
  63. | Context | `context.yaml` | Mode hierarchy, notification dedup, TV sleep timers |
  64. | Health | `health.yaml` | Integration watchdogs with retry, stale sensors, battery alerts |
  65. | AC | `ac.yaml` | Solar-driven AC heating, manual mode bypass with auto-revert |
  66. | Appliance | `appliance.yaml` | WiFi appliance state machine, cycle tracking, solar reminders |
  67. | Irrigation | `irrigation.yaml` | Per-zone scheduling with front/back groups, weather + seasonal skip, run history |
  68. ### Dashboard
  69. React 19 + TypeScript + Tailwind v4, deployed as an HA `panel_custom` via `make deploy-dashboard`.
  70. <p align="center">
  71. <img src="docs/images/room-popup.png" width="195" alt="Room popup -- light brightness and color temp sliders, climate zone, media">
  72. <img src="docs/images/ac-popup.png" width="195" alt="AC control -- temperature stepper, mode/fan/swing, manual override timer">
  73. <img src="docs/images/remote.png" width="195" alt="TV remote -- touchpad, app strip, media controls, volume slider">
  74. <img src="docs/images/settings.png" width="195" alt="Settings -- schedules, temperature presets, motion timeouts">
  75. </p>
  76. <p align="center"><em>Room controls &nbsp;·&nbsp; AC popup &nbsp;·&nbsp; TV remote &nbsp;·&nbsp; Settings (every value is configurable)</em></p>
  77. - Room cards with temperature, humidity, motion, light status
  78. - Bottom-sheet popups with light sliders, climate controls, media players
  79. - Camera streams (MSE on desktop, WebRTC on mobile/iOS) with snapshot history
  80. - EV charger card with solar/fast/manual modes and charging cost breakdown
  81. - Irrigation view with per-zone scheduling, weather/seasonal skip, a per-zone settings popup, and run history
  82. - Unified control system with 4-phase state machine: debounce, inflight tracking, post-confirmation hold
  83. See [dashboard/CLAUDE.md](dashboard/CLAUDE.md) for the full development guide.
  84. > **Tip: Make the dashboard your default view**
  85. > HA always opens to a Lovelace dashboard by default. To land on the custom panel instead, install [Custom Sidebar](https://github.com/Villhellm/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](SETUP.md#step-10-make-the-dashboard-the-default-view-optional) for details.
  86. ### Health Monitoring & Charts
  87. <p align="center">
  88. <img src="docs/images/health.png" width="250" alt="Health -- boiler diagnostics, heating timeline, per-zone temperature charts">
  89. <img src="docs/images/energy-chart.png" width="250" alt="Energy chart -- solar production, house/charger consumption, forecast, cost">
  90. </p>
  91. <p align="center"><em>Boiler diagnostics &amp; heating timeline &nbsp;·&nbsp; Solar production with charging breakdown</em></p>
  92. - Heating timeline showing boiler and per-zone activity over the day
  93. - Per-zone temperature charts with target lines and TRV calibration offsets
  94. - Solar production chart with house/charger/forecast overlays and daily cost breakdown
  95. - Integration health status with watchdog retry history
  96. ### Validation Tools
  97. ```bash
  98. make validate # Runs all three layers:
  99. # 1. YAML syntax validation
  100. # 2. Entity reference checking
  101. # 3. Official HA configuration validation
  102. ```
  103. Pre-push hooks block broken configs automatically. Template placeholder IDs (`your_*`) are skipped.
  104. ### Entity Rename Skill
  105. Batch rename HA entities to follow a consistent `domain.{room}_{descriptor}` convention:
  106. ```
  107. entity-rename # Discover → propose → approve → execute → verify
  108. ```
  109. 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.
  110. ### Recipes (optional)
  111. A full meal-planning feature built on the [Mealie](https://mealie.io/) add-on, shipped as an **optional template** in `docs/templates/recipes/` (it requires Mealie + an LLM API key, so it's opt-in rather than core):
  112. - Recipe library with search, recipe detail, and a full-screen **cook mode** (per-step timers + screen wake lock)
  113. - Weekly meal plan, shopping list, and a "tonight's dinner" card on the Home view
  114. - **Paste-to-import**: drop in any recipe text/URL and an LLM extracts a structured recipe — ingredients with unit conversion, per-serving nutrition, and step timers — straight into Mealie
  115. `docs/templates/recipes/README.md` has the full setup guide (prerequisites, the dashboard→script→LLM→Mealie dependency chain, and 8 install steps).
  116. ### Versioning & Upgrades
  117. The kit is versioned with semver and a structured, agent-readable changelog ([`CHANGELOG.md`](CHANGELOG.md), rendered from `kit-changelog.yaml`). Two skills manage the lifecycle:
  118. - **`release`** (producer) — curates commits since the last tag into changelog entries, derives the version bump, renders `CHANGELOG.md`, and cuts a tagged GitHub release.
  119. - **`upgrade`** (consumer) — pulls a newer kit version into your *diverged* install, applying only the changes still relevant to you (it checks each change against your code), on a work branch — never a blind merge. See [Updating](#updating).
  120. ![latest release](https://img.shields.io/github/v/release/dcb/homeassistant-claude-kit?label=release)
  121. ### Institutional Knowledge
  122. 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.
  123. ## Project Structure
  124. ```
  125. config/ # HA config files (synced via rsync)
  126. automations/ # Split automation files by domain
  127. scripts/ # Split script files
  128. configuration.yaml # Main config + input helpers
  129. dashboard/ # React 19 custom panel
  130. src/components/ # Cards, controls, popups, layout
  131. src/hooks/ # useHistory, useWeatherForecast, useGo2RtcStream
  132. src/lib/ # entities.ts, areas.ts, control hooks
  133. src/views/ # Home, Climate, Energy, Irrigation, Security, Settings, Health
  134. docs/
  135. templates/config/ # Automation YAML templates
  136. templates/recipes/ # Optional Mealie recipes feature (dashboard + config + guide)
  137. solutions/ # 34 debugging lessons and patterns
  138. system-*.md # System documentation (always current)
  139. brainstorms/ # Feature exploration documents
  140. plans/ # Implementation plans
  141. tools/ # Validation and entity management scripts (incl. validate_changelog.py)
  142. .claude/
  143. skills/ # AI skills (setup-infrastructure, setup-customize, entity-rename, release, upgrade)
  144. hooks/ # Pre/post tool-use validation hooks
  145. kit-changelog.yaml # Structured changelog (source of truth) → renders CHANGELOG.md
  146. .kit-version # Which kit version this install is based on
  147. Makefile # pull, push, validate, deploy-dashboard
  148. ```
  149. ## Available Commands
  150. | Command | What it does |
  151. |---------|-------------|
  152. | `make pull` | Pull latest config from HA |
  153. | `make push` | Validate + push to HA + reload |
  154. | `make diff` | Dry run -- preview what push would sync |
  155. | `make validate` | Run all validation tests |
  156. | `make backup` | Create timestamped backup |
  157. | `make entities` | Explore available HA entities |
  158. | `make deploy-dashboard` | Build + deploy React dashboard to HA |
  159. ## Architecture
  160. Configuration flows through an rsync-based pipeline:
  161. 1. **Edit locally** -- YAML files in `config/`, React components in `dashboard/`
  162. 2. **Validate** -- hooks run on every file edit (YAML syntax, entity refs, TypeScript)
  163. 3. **Push** -- `make push` syncs to HA via rsync over SSH (`.storage/` is protected)
  164. 4. **Reload** -- automations, scripts, and templates reload without HA restart
  165. 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).
  166. ## Updating
  167. The kit is versioned (see [`CHANGELOG.md`](CHANGELOG.md)). To pull later fixes and features into an
  168. install that has diverged from the template, run the **`upgrade` skill** in Claude Code:
  169. > "upgrade the kit"
  170. It reads the structured changelog (`kit-changelog.yaml`), works out which changes are still relevant to
  171. *your* install, and applies them on a branch — rather than a blind `git pull`/merge that would fight your
  172. customizations. Your install-specific files stay untracked and out of its way: `config/` (your real HA
  173. config), `.env` / `dashboard/.env.local` (credentials), and `setup-state.json`. The dashboard's
  174. `entities.ts` / `areas.ts` ship as scaffolds and are generated for your home by `setup-customize`.
  175. > **Manual fallback** (advanced): the kit's tracked files can be updated with `git pull` from the kit
  176. > remote, then `cd dashboard && npm install && npm run build && cd .. && make deploy-dashboard`. Prefer
  177. > the `upgrade` skill — it handles divergence and won't clobber your generated `entities.ts`/`areas.ts`.
  178. > **First upgrade:** the `upgrade` skill ships in **v0.3.0**, so an install set up from an earlier
  179. > version won't have it yet — do that one hop with the manual fallback above (or copy
  180. > `.claude/skills/upgrade/` from the kit). From v0.3.0 onward, `upgrade` drives everything.
  181. ## Acknowledgments
  182. This project builds on the work of others:
  183. - **[philippb/claude-homeassistant](https://github.com/philippb/claude-homeassistant)** -- Makefile, rsync workflow, validation tools, CLAUDE.md structure, and the original vision of AI-managed HA config
  184. - **[danbuhler/claude-code-ha](https://github.com/danbuhler/claude-code-ha)** -- `ha-api` and `ha-ws` CLI tools for querying HA state, managing the entity/device/area registries, and renaming entities via WebSocket -- all from the HA instance over SSH
  185. - **[shannonhochkins/ha-component-kit](https://github.com/shannonhochkins/ha-component-kit)** -- `@hakit/core` provides the React WebSocket connection and entity state hooks that power the dashboard
  186. - **[Compound Engineering](https://github.com/EveryInc/compound-engineering-plugin)** -- the Claude Code plugin that powers the brainstorm → plan → implement → review → learn workflow
  187. - **[Home Assistant](https://www.home-assistant.io/)** -- the platform
  188. - **[Claude Code](https://claude.com/claude-code)** -- the AI development tool
  189. ## License
  190. MIT -- see [LICENSE](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.