Skip to content
Back to search

aurora-smart-home

Aurora Smart Home - Claude Skills for Home Assistant, ESPHome, Node-RED, and IoT product development

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/tonylofgren--aurora-smart-home/badge.svg)](/listings/tonylofgren--aurora-smart-home)

HTML

<a href="/listings/tonylofgren--aurora-smart-home"><img src="/api/listings/tonylofgren--aurora-smart-home/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.

Choose the tool you use. Aurora is installed into Claude Code or Codex on your computer; it is not a Home Assistant add-on.

| Your tool | Start here | |-----------|------------| | Claude Code | [Install with one command](#install-for-claude-code) | | OpenAI Codex CLI | [Install with two commands](#install-for-openai-codex) |

Install for Claude Code

You need [Claude Code](https://claude.com/claude-code) installed and signed in. Inside Claude Code **2.1.275 or later**, paste:

/plugin install aurora --marketplace tonylofgren/aurora-smart-home

Review the plugin and choose **Install for you** to use Aurora across your projects. Follow any reload instruction shown by Claude Code, then start Aurora:

/aurora:aurora

**Check it worked:** open `/plugin` and look for Aurora on the Installed tab. Then ask: "Use Aurora to help me build a temperature sensor with ESPHome."

<details> <summary>Older Claude Code, or installing from a terminal?</summary>

If your version does not recognize `--marketplace`, use these two commands inside Claude Code:

/plugin marketplace add tonylofgren/aurora-smart-home
/plugin install aurora@aurora-smart-home

To install from your operating system's terminal instead, Claude Code **2.1.292 or later** supports:

claude plugin install aurora --marketplace tonylofgren/aurora-smart-home

Start Claude Code after installation, then run `/aurora:aurora`.

</details>

[Official Claude Code installation instructions](https://code.claude.com/docs/en/discover-plugins#add-a-marketplace-and-install-in-one-command).

Install for OpenAI Codex

You need the [OpenAI Codex CLI](https://developers.openai.com/codex) installed and signed in. In your operating system's terminal, run these commands one at a time:

codex plugin marketplace add https://github.com/tonylofgren/aurora-smart-home.git
codex plugin add aurora@aurora-smart-home

**Check it worked:** run the following and confirm Aurora is installed:

codex plugin list --marketplace aurora-smart-home

Start a new `codex` session and ask: "Use Aurora to help me build a temperature sensor with ESPHome." The specialist skills load from your question; `/aurora:aurora` is the Claude Code entry point.

If `codex plugin` is not recognized, update your Codex CLI before retrying. To refresh the Aurora marketplace later, run `codex plugin marketplace upgrade aurora-smart-home`.

Alternatively, skip the plugin install and run `codex` from inside a clone of this repo: [`AGENTS.md`](AGENTS.md) routes Codex to the right `SKILL.md` per domain.

---

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.

.claude-plugin/marketplace.json · Manifest · 24 lines

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

  1. {
  2. "name": "aurora-smart-home",
  3. "version": "1.20.0",
  4. "description": "Aurora Smart Home - Claude Skills for Home Assistant, ESPHome, Node-RED, and IoT product development",
  5. "owner": {
  6. "name": "Tony Löfgren"
  7. },
  8. "plugins": [
  9. {
  10. "name": "aurora",
  11. "description": "Aurora Smart Home - skills for Home Assistant, ESPHome, Node-RED, custom integrations, API catalog, and dashboard design",
  12. "source": "./",
  13. "skills": [
  14. "./home-assistant",
  15. "./esphome",
  16. "./ha-integration-dev",
  17. "./node-red",
  18. "./api-catalog",
  19. "./ha-dashboard-design"
  20. ],
  21. "commands": ["./commands"]
  22. }
  23. ]
  24. }
README.md · README · 810 lines

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

  1. <p align="center">
  2. <img src="assets/banner.jpg" alt="Aurora Smart Home - Claude Code and Codex Skills" width="100%">
  3. </p>
  4. # Aurora Smart Home
  5. **Describe what you want to build. Get back automations, firmware,
  6. integrations, and dashboards that already passed validation.**
  7. Aurora is a Claude Code plugin with 21 smart home specialists backed by
  8. verified reference data. Home Assistant automations and dashboards, ESPHome
  9. firmware, HACS-ready Python integrations, Node-RED flows: every request is
  10. routed to the right specialist, and every pin, entity ID, I2C address, and
  11. API pattern is checked before code is generated. Ask for something that
  12. cannot work, a reserved GPIO or an automation triggering on an entity that
  13. does not exist, and Aurora refuses, shows you why, and hands you the fix
  14. instead of code that fails silently.
  15. [![Claude Code](https://img.shields.io/badge/Claude_Code-Skills-7c3aed.svg)](https://docs.anthropic.com/en/docs/claude-code)
  16. [![Home Assistant](https://img.shields.io/badge/Home_Assistant-2024.x--2026.x-41BDF5.svg)](https://www.home-assistant.io/)
  17. [![ESPHome](https://img.shields.io/badge/ESPHome-2026.10.0-000000.svg)](https://esphome.io/)
  18. [![Version](https://img.shields.io/badge/Version-v1.20.0-success.svg)](CHANGELOG.md)
  19. [![Validated](https://img.shields.io/badge/Validated-against_datasheets-success.svg)](aurora/references/)
  20. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  21. [![Support Nabu Casa](https://img.shields.io/badge/Support_HA-Nabu_Casa-3b8cd3.svg)](https://www.nabucasa.com)
  22. ---
  23. > ⚠️ **Use at your own risk.** Aurora generates code and recommendations for
  24. > educational purposes. Smart home projects involve mains electricity, batteries,
  25. > and devices that control locks, water, heating, and gas. AI-generated configs
  26. > can be plausible but wrong. The maintainers, contributors, and Anthropic accept
  27. > no liability for property damage, personal injury, data loss, or any other harm.
  28. > See [DISCLAIMER.md](DISCLAIMER.md) for full terms.
  29. ---
  30. ## Aurora in 10 seconds
  31. In Claude Code 2.1.275 or later, install Aurora with:
  32. ```text
  33. /plugin install aurora --marketplace tonylofgren/aurora-smart-home
  34. ```
  35. Confirm the installation, then run `/aurora:aurora`.
  36. Using Codex or an older Claude Code? See the [installation guide](#quick-start).
  37. Then just describe it. One request is enough for a complete build: Aurora
  38. delivers the ESPHome firmware, the Home Assistant automation, and the
  39. dashboard as one coherent project, wired together end to end so the entity
  40. the firmware creates is the entity the automation triggers on and the
  41. dashboard shows.
  42. > **You:** motion light for the hallway: sensor on ESP32, automation in
  43. > Home Assistant, a tile on the dashboard
  44. >
  45. > **Aurora:** plans three specialists working from one shared snapshot:
  46. >
  47. > ```
  48. > Volt (firmware) validates board + pins before writing YAML,
  49. > creates binary_sensor.hallway_motion
  50. > Sage (automation) triggers on binary_sensor.hallway_motion,
  51. > modern triggers:/actions: syntax
  52. > Iris (dashboard) places the same entity on the room view
  53. > ```
  54. >
  55. > Anything impossible is refused with a concrete fix instead of generated:
  56. >
  57. > ```
  58. > ❌ Problem: GPIO 19/20 are reserved for USB on the ESP32-S3 DevKit.
  59. > 🔧 Fix: Use GPIO 8 (SDA) and GPIO 9 (SCL), the board's default
  60. > I2C pins.
  61. > ```
  62. >
  63. > If Sage's automation references an entity Volt never creates, Aurora
  64. > raises the conflict to you instead of shipping broken YAML. Delivery is
  65. > a project folder on disk, not a paste in chat:
  66. >
  67. > ```
  68. > hallway-motion/
  69. > ├── README.md ← BOM with prices, wiring table + diagram,
  70. > │ install steps, troubleshooting, recovery
  71. > ├── hallway-motion.yaml ← ESPHome firmware (Volt)
  72. > ├── automations.yaml ← HA automation (Sage)
  73. > ├── dashboard.yaml ← Lovelace view (Iris)
  74. > └── secrets.yaml.example ← WiFi + API key template
  75. > ```
  76. No hardware involved? Aurora works the same for pure software requests:
  77. > **You:** lights on at sunset, off at midnight
  78. >
  79. > **Aurora:** a Home Assistant automation in modern `triggers:` /
  80. > `actions:` syntax, where every entity it references is verified to exist.
  81. > **You:** Python integration for the Acme cloud API, HACS ready
  82. >
  83. > **Aurora:** the full `custom_components/` structure with config flow,
  84. > coordinator, and the async pitfalls (`datetime.now()`, blocking I/O)
  85. > already caught.
  86. Plain AI codegen gives you *plausible*. Aurora gives you *checked*:
  87. [12 validators](#validation-and-safety) block bad pins, I2C address
  88. collisions, wrong voltages, missing entities, async bugs, and OTA-bricking
  89. configs before any code reaches you, whether the output is ESPHome YAML, a
  90. Home Assistant automation, Python, or a Node-RED flow.
  91. ---
  92. ## What's new: ESPHome 2026.10 and custom dashboards (v1.20.0, October 2026)
  93. - **ESPHome coverage through 2026.10.0:** upgrade guides for September and October, official references for every new component, and [32 reusable examples](esphome/assets/templates/2026-10/README.md).
  94. - **Encrypted OTA migration:** updated device templates, secret generators and step-by-step guidance for existing devices, including MQTT-only installations.
  95. - **Your own dashboard identity:** custom layouts, typography and themes, with a [responsive Editorial starter](ha-dashboard-design/assets/custom-editorial/README.md) that goes beyond Home Assistant's standard appearance.
  96. Earlier releases (ESPHome 2026.8.0, ESPHome 2026.7.0, XIAO boards, the recipe
  97. library, verified JLCPCB part numbers, fab-ready hardware delivery, and
  98. more): see [CHANGELOG.md](CHANGELOG.md).
  99. <details>
  100. <summary><strong>Previous release notes</strong> (v1.9.2 - v1.19.0)</summary>
  101. ## What's new: OpenAI Codex support (v1.19.0, August 2026)
  102. - **OpenAI Codex CLI support:** a two-command install via the codex plugin marketplace, with AGENTS.md routing so Codex users get the same specialist routing as Claude Code. Also works from a plain repository clone, no plugin install required.
  103. - **Model guidance refreshed to the Claude 5 family:** Opus 5 recommended for complex design work (PCB layout, integration architecture), Sonnet 5 as the workhorse for everyday builds and automations.
  104. - **Build Principles baked into every specialist:** simplest working config first, reuse existing patterns before adding new dependencies, and a validation step built into every delivery.
  105. ## What's new: ESPHome 2026.8.0 support (v1.18.0, August 2026)
  106. - **Full ESPHome 2026.8.0 release guide:** Bluetooth Low Energy now works across more chip families (Raspberry Pi Pico W, Beken BK72xx, LibreTiny LN882H), with a breaking-change migration checklist for the `ble_hub_id` rename, `voc_index`/`nox_index` sensor keys, and the new LED strip `channel_colors` key.
  107. - **New device support with ready-to-flash configs:** 60 GHz presence radar (LD6002B), Hörmann garage door control, DS248x 1-Wire bridges, and ad-hoc Modbus read/write actions straight from YAML.
  108. - **Networking and reliability:** dual Ethernet+WiFi with automatic failover on ESP32, and multi-key OTA signature verification for signing-key rotation.
  109. ## What's new: ESPHome 2026.7.0 support (v1.17.0, July 2026)
  110. - **Full ESPHome 2026.7.0 release guide:** native ESP-IDF and nRF Connect SDK toolchains are now the default build backend, with an upgrade checklist, a breaking-change table, and a "what did not change" reassurance section so upgrades do not surprise you.
  111. - **New device support with ready-to-flash configs:** the QMI8658 IMU, Divoom Pixoo 64 LED matrix, IT8951 e-paper (M5Paper), and new touch controllers, plus a Modbus meter recipe and an animated, auto-rotating LVGL screen.
  112. - **Security recipes:** opt-in NVS encryption, OTA downgrade protection, and the new provisioning window for products that ship unconfigured, all wired into a single hardened-node example.
  113. ## What's new: XIAO boards, more air-quality sensors, current platform data (v1.16.0, July 2026)
  114. - **Seeed XIAO family in the catalog:** board profiles for the XIAO ESP32-C3, ESP32-C6, and ESP32-S3 with verified pin maps, strapping pins, LiPo charging data, and the C6 antenna-switch GPIOs, so tiny battery builds get real pin validation.
  115. - **Air quality beyond CO2:** PMS5003 particulate (PM1.0/PM2.5/PM10) and SGP40 VOC index sensor profiles join the catalog (now 16 parts), both with live-verified JLCPCB part numbers.
  116. - **Aurora routes on current releases:** platform data now covers HA 2026.6/2026.7 and ESPHome 2026.5/2026.6, including the HA 2026.6 removal of legacy `platform: template` sensors, plus sharper routing keywords (mmWave/radar/presence, DLMS smart meters, SkyConnect).
  117. ## What's new: ESPHome 2026.6.0 support (v1.15.0, June 2026)
  118. - **New ESPHome release reference:** Aurora now knows ESPHome 2026.6.0, with an upgrade checklist, breaking changes, and copy-ready examples, so generated firmware matches the current release instead of older patterns.
  119. - **New hardware covered:** the motion/IMU framework (BMI270 and LSM6DS tilt and orientation), the PCM5122 HiFi audio DAC, the router speaker for live SPDIF/analog switching, the XDB401 pressure sensor, and FTDI/Prolific USB-serial adapters, each with a worked config.
  120. - **Safer upgrades:** Aurora warns that ESP8266 now defaults to WPA2 (legacy routers need a one-line opt-out) and shows how `enable_on_boot: false` now frees real RAM on WiFi and ethernet.
  121. ## What's new: two new recipes and four more sensors (v1.14.0, June 2026)
  122. - **Two new recipes:** `daylight-lights` dims or switches lights to match the measured ambient light in a room, and `dc-power-monitor` measures the current and power a DC device or circuit draws. The library is now 14 curated starting points.
  123. - **Four more verified sensors** in the catalog (now 14 parts): SHT31 and AHT20 (higher-accuracy temperature/humidity), BH1750 (ambient light), and INA219 (DC current/power), each with a real, in-stock JLCPCB part number.
  124. - **Sharper existing recipes:** weather-station can swap in SHT31/AHT20 for better accuracy, and motion-light now has a real light sensor (BH1750) behind its lux threshold.
  125. ## What's new: out-of-stock warnings (v1.13.1, June 2026)
  126. - **No more checkout surprises:** when a part you picked is out of stock or running low at JLCPCB, Aurora now flags it in the BOM and calls it out in the README, so you can swap to an alternative before you order instead of finding out at checkout.
  127. - **Live stock in the component catalog:** the verified-parts catalog tracks JLCPCB stock status (in stock / low / out of stock), refreshed automatically each month.
  128. ## What's new: stronger delivery and protocol checks (v1.13.0, June 2026)
  129. Three additive upgrades that make Aurora's output more trustworthy.
  130. - **Conformance levels in the delivery check:** `check-delivery.py` now reports whether a project reaches minimal, standard, or strict, and you can gate at the level you want. The language check is now definitive (every doc in a project must share one language) instead of a heuristic, and there is a drop-in CI workflow template so you can gate your own project repos.
  131. - **A worked DEEP-mode demo:** a complete CO2 project shows three specialists (firmware, automation, dashboard) building through one shared snapshot, with a replay test that proves the hand-off protocol end to end.
  132. - **An eval regression gate:** the routing and delivery eval scores are pinned to a golden baseline, so a future change cannot quietly weaken how Aurora routes requests or what it delivers.
  133. ## What's new: recipe library (v1.12.0, June 2026)
  134. Aurora can now start you from a curated recipe instead of a blank page.
  135. - **12 ready-made starting points:** CO2 monitor, motion light, weather station, fridge/freezer monitor, room presence, home/away routine, energy dashboard, notification hub, vacation mode, greenhouse, smart thermostat, and a button scene controller.
  136. - **Describe a goal, get suggestions:** say something broad like "I want to do something about air quality" and Aurora offers the closest recipes, always with "start from scratch" as an option.
  137. - **Pick one and Aurora builds it:** the full project folder is generated from the recipe (hardware with verified part numbers where applicable, automation pattern, and dashboard), then you customise the handful of parameters that matter (thresholds, rooms, schedules).
  138. - **Across the board:** recipes span sensor builds and pure Home Assistant automations that need no new hardware, and each links the full worked example when one exists.
  139. ## What's new: verified part numbers + validated netlists (v1.11.0, June 2026)
  140. The fab-ready pipeline from v1.10.0 is now complete and verified end to end.
  141. - **Real JLCPCB part numbers:** 9 of 10 sensor profiles carry LCSC numbers verified live against the JLCPCB parts catalog, and a monthly sync keeps their library status current. Hardware projects get orderable BOMs instead of placeholders.
  142. - **Machine-validated netlists:** every custom-PCB delivery now runs `validate_schematic.py`, which catches shorts (one pin in two nets), undeclared components, duplicate nets, and missing ground before anything reaches a fab. The OpenSCAD enclosure template is render-verified to produce a printable, manifold STL.
  143. - **Current ESPHome syntax:** all ESPHome examples and references use the actions terminology (`api: actions:`, `homeassistant.action`) that ESPHome adopted in line with Home Assistant. Old configs keep working; new output follows the current docs.
  144. - **Smarter multi-agent builds:** the debugging, QA, review, and documentation specialists now coordinate through the shared project snapshot, so a debugging pass mid-project sees the real board, pins, and entity IDs instead of guessing from conversation history.
  145. ## What's new: fab-ready hardware delivery (v1.10.0, June 2026)
  146. Hardware projects can now go from idea to a PCB order without leaving Aurora.
  147. - **Machine-readable manufacturing exports:** custom-PCB and production projects ship `hardware/schematic.json` (a netlist you can tick off while redrawing in KiCad) and `hardware/BOM.csv` in the exact column format JLCPCB assembly expects. Part numbers are never invented; `TBD` marks parts still waiting for sourcing.
  148. - **Printable enclosures:** a parametric OpenSCAD template generates a two-part box with PCB standoffs, ventilation slots, cable opening, and an optional sensor window, sized from your board dimensions.
  149. - **Safer and smarter orchestration:** projects involving batteries, mains power, actuators, water, or outdoor mounting now always start with a hazard analysis before any firmware is generated, and requests that span several specialists are routed with clear tiebreaker rules.
  150. ## What's new: modern syntax everywhere + 4 new references (v1.9.3, June 2026)
  151. Every YAML example in the entire plugin now uses current Home Assistant syntax.
  152. - **Modern syntax everywhere:** all references, starter templates, dashboards, and the 27 complete examples now use `triggers:`, `conditions:`, `actions:`, `action:` calls, and `perform-action` dashboard taps. The migration guide documents the 2024.8 and 2024.10 renames with before/after examples, so older configs are easy to bring forward.
  153. - **Four new reference files:** ESPHome `packages:` for modular fleet configs (20-line device files), reusable Jinja2 macros via `custom_templates/`, HA labels and categories for organizing large installs, and Node-RED Dashboard 2.0 for building web panels.
  154. - **Deeper troubleshooting:** automation debugging with traces (opening them, common findings, a "my automation did not run" flowchart) and git-based Node-RED Projects for versioning flows.
  155. ## What's new: HA reference refresh (v1.9.2, May 2026)
  156. The Home Assistant YAML skill's reference library has been brought up to date against the official HA documentation snapshot from 2026-05-30.
  157. - **Dashboard actions** — the `actions.md` reference now covers all seven Lovelace tap/hold/double-tap action types (`more-info`, `toggle`, `perform-action`, `navigate`, `url`, `assist`, `none`) including confirmation dialogs. Also added: response variables for capturing return data from calendar, weather, and other actions that produce structured output.
  158. - **Device-specific conditions and triggers** — `conditions.md` gained a Device-Specific Conditions section covering alarm, climate, timer, calendar (`calendar.is_event_active`), and more, plus a selection guide. `triggers-advanced.md` gained a Device Trigger Inventory spanning 18+ device domains and a dedicated Calendar Trigger section.
  159. - **Modern syntax throughout** — deprecated `service:`, `platform:`, and singular automation keys (`trigger:`, `condition:`, `action:`) replaced with `action:`, `trigger: state`, `triggers:`, `conditions:`, `actions:` across all four core reference files. The skill now also lists all 50 reference files in its Quick Reference table.
  160. ## What's new: ESPHome 2026.5.0 (May 2026)
  161. Aurora now targets ESPHome 2026.5.0. Twelve user-visible changes landed in this
  162. release at once - some of them (battery life, Bluetooth proxy stability, the
  163. audio stack) take effect the moment you reflash, no YAML changes required. Others
  164. unlock things that were not possible before: synchronized whole-house audio from
  165. ESP32s, Zigbee built into core for the C6 and H2, and a `radio_frequency` entity
  166. type that finally treats RF transceivers as first-class devices in Home Assistant.
  167. - **Multi-room synchronized audio via the new Sendspin stack.** One device runs
  168. the hub, every other device runs a per-room player, and they stay in lock-step
  169. on the LAN. The decoder work in this release is tuned so a non-PSRAM ESP32 can
  170. actually keep up with 2-channel Opus, which previously required an S3 with
  171. PSRAM. Each room has its own `delay_compensation` to align with whatever
  172. amp/DAC chain you wire up.
  173. - **Zigbee on ESP32-H2 and C6, no external component required.** A Xiao C6 or
  174. H2 module can now be flashed straight into a battery-powered Zigbee end device
  175. or router; both ZHA and zigbee2mqtt pick it up over standard clusters without
  176. custom converters. New `on_join` automation trigger and `power_source` field
  177. for advertising battery vs mains.
  178. - **`radio_frequency` is now a first-class HA entity type.** The entity itself
  179. has no knowledge of which RF chip is wired underneath, so a CC1101, RFM69,
  180. SX127x, or custom external all work through the same YAML triggers. Pair with
  181. the new `ir_rf_proxy` platform if you want HA to know your frequency range.
  182. - **Battery devices noticeably last longer.** The runtime now actually runs
  183. components at the cadence you ask for, and the watchdog feeding cost on
  184. ESP-IDF has finally been retuned (the original 3 ms throttle was set for a
  185. 2019 codepath that cost ~100 ns per feed; the IDF port pushed that to 10 µs
  186. per feed without anyone noticing). A reference Thread device measured 2.0 mA
  187. dropping to 1.1 mA. New `esp32: watchdog_timeout:` knob lets you trade
  188. responsiveness for sleep time, 5 to 60 seconds.
  189. - **Bluetooth proxy reliability fix.** The `status=133` GATT failures that have
  190. hit Yale and August lock owners for years are gone. The proxy now holds BT
  191. priority during active connections instead of releasing it after the
  192. handshake.
  193. - **ESPHome Device Builder is in public beta.** A separate web dashboard with a
  194. visual component editor alongside Monaco YAML, a firmware job queue, labels,
  195. areas, device cloning, out-of-sync badges, cross-config YAML search, a YAML
  196. diff view, and a Ctrl-K command palette. Available via the "ESPHome (beta)"
  197. Home Assistant add-on; the classic dashboard is still default.
  198. - **Native ESP-IDF toolchain alongside PlatformIO.** `esp32: toolchain: esp-idf`
  199. switches the build system to `idf.py`. ESP-IDF v6.0.1 readiness work landed in
  200. the same release.
  201. - **40 kB more internal RAM on PSRAM boards** via `esp32_ble: use_psram: true`,
  202. which moves the Bluedroid stack into SPIRAM.
  203. - **SPDIF speaker output** through any GPIO using the new `mode: spdif` setting
  204. on `i2s_audio`. Drive an optical TOSLINK module or a 75-ohm coax line directly
  205. from the ESP, no external DAC.
  206. - **ESP32-P4 USB high-speed transfers** via `usb_host: max_packet_size: 512`.
  207. Previously P4 USB was stuck on 64-byte full-speed packets.
  208. - **Locks gained OPENING and OPEN states** for motorized smart locks where HA
  209. needs to distinguish "bolt disengaged" from "door is hanging open". Existing
  210. LOCKED/UNLOCKED-only locks are unaffected.
  211. - **`modbus_server` is its own component now.** If you used `modbus_controller`
  212. in server mode, move the keys to a top-level `modbus_server:` block:
  213. `server_registers:` becomes `registers:`, `server_courtesy_response:` becomes
  214. `courtesy_response:`. Worth about 60% flash savings on the way out.
  215. Full details, breaking changes, and copy-paste recipes: [`esphome/references/release-2026-5.md`](./esphome/references/release-2026-5.md).
  216. </details>
  217. ---
  218. ## What is Aurora
  219. Aurora is a community plugin for [Claude Code](https://claude.com/claude-code)
  220. and the [OpenAI Codex CLI](https://developers.openai.com/codex). You install it
  221. once. After that, every smart home request you make ("build a temperature
  222. sensor on ESP32", "automate my lights at sunset", "publish this integration to
  223. HACS") is handed to a specialist agent that consults machine-readable board
  224. and component profiles before generating code.
  225. You never pick a skill or paste documentation yourself. Ask about ESPHome and
  226. the ESPHome references load; ask for an integration and the integration
  227. development rules load. The model does not have to remember whether a given
  228. ESP32 pin is safe or how a modern config flow is structured, because the
  229. relevant reference file is pulled in exactly when the task needs it.
  230. If the GPIO you asked for is reserved by USB, Aurora says so. If two I2C sensors
  231. collide on address 0x76, Aurora says so. If an automation references an entity
  232. the firmware never creates, Aurora says so. The reference data is the source of
  233. truth, not the model's training memory.
  234. No runtime dependencies. The plugin is markdown and JSON. Claude reads it.
  235. Python and pytest are only used by maintainers to keep the reference data
  236. correct.
  237. <details>
  238. <summary><strong>How the pieces fit together</strong> (plugin, command, skill, agent, validator)</summary>
  239. | Term | Means |
  240. |------------|---------------------------------------------------------------------------------------|
  241. | Plugin | `aurora@aurora-smart-home`. The single thing you install. |
  242. | Command | `/aurora:aurora`. Opens the orchestrator. The fastest entry point. |
  243. | Skill | A topic module (`esphome`, `home-assistant`, etc.) that activates on keywords. |
  244. | Agent | A named specialist (Volt, Sage, Ada, etc.) the orchestrator hands work to. |
  245. | Validator | A reference spec the specialist must run before generating code. |
  246. | Snapshot | `aurora-project.json`. Shared state when more than one agent is involved in a task. |
  247. </details>
  248. > Already comfortable with Claude Code skills? Skip to
  249. > [How Aurora works](#how-aurora-works),
  250. > [Validation and safety](#validation-and-safety),
  251. > or [Included skills](#included-skills).
  252. ---
  253. ## Quick start
  254. Choose the tool you use. Aurora is installed into Claude Code or Codex on your
  255. computer; it is not a Home Assistant add-on.
  256. | Your tool | Start here |
  257. |-----------|------------|
  258. | Claude Code | [Install with one command](#install-for-claude-code) |
  259. | OpenAI Codex CLI | [Install with two commands](#install-for-openai-codex) |
  260. ### Install for Claude Code
  261. You need [Claude Code](https://claude.com/claude-code) installed and signed in.
  262. Inside Claude Code **2.1.275 or later**, paste:
  263. ```text
  264. /plugin install aurora --marketplace tonylofgren/aurora-smart-home
  265. ```
  266. Review the plugin and choose **Install for you** to use Aurora across your
  267. projects. Follow any reload instruction shown by Claude Code, then start Aurora:
  268. ```text
  269. /aurora:aurora
  270. ```
  271. **Check it worked:** open `/plugin` and look for Aurora on the Installed tab.
  272. Then ask: "Use Aurora to help me build a temperature sensor with ESPHome."
  273. <details>
  274. <summary>Older Claude Code, or installing from a terminal?</summary>
  275. If your version does not recognize `--marketplace`, use these two commands
  276. inside Claude Code:
  277. ```text
  278. /plugin marketplace add tonylofgren/aurora-smart-home
  279. /plugin install aurora@aurora-smart-home
  280. ```
  281. To install from your operating system's terminal instead, Claude Code
  282. **2.1.292 or later** supports:
  283. ```sh
  284. claude plugin install aurora --marketplace tonylofgren/aurora-smart-home
  285. ```
  286. Start Claude Code after installation, then run `/aurora:aurora`.
  287. </details>
  288. [Official Claude Code installation instructions](https://code.claude.com/docs/en/discover-plugins#add-a-marketplace-and-install-in-one-command).
  289. ### Install for OpenAI Codex
  290. You need the [OpenAI Codex CLI](https://developers.openai.com/codex)
  291. installed and signed in. In your operating system's terminal, run these
  292. commands one at a time:
  293. ```sh
  294. codex plugin marketplace add https://github.com/tonylofgren/aurora-smart-home.git
  295. codex plugin add aurora@aurora-smart-home
  296. ```
  297. **Check it worked:** run the following and confirm Aurora is installed:
  298. ```sh
  299. codex plugin list --marketplace aurora-smart-home
  300. ```
  301. Start a new `codex` session and ask: "Use Aurora to help me build a temperature
  302. sensor with ESPHome." The specialist skills load from your question;
  303. `/aurora:aurora` is the Claude Code entry point.
  304. If `codex plugin` is not recognized, update your Codex CLI before retrying.
  305. To refresh the Aurora marketplace later, run
  306. `codex plugin marketplace upgrade aurora-smart-home`.
  307. Alternatively, skip the plugin install and run `codex` from inside a clone of
  308. this repo: [`AGENTS.md`](AGENTS.md) routes Codex to the right `SKILL.md`
  309. per domain.
  310. ---
  311. ## Try your first prompt
  312. After starting Aurora in Claude Code, or opening a new Codex session, try any of these:
  313. | You say | Aurora does |
  314. |--------------------------------------------------------|----------------------------------------------------------------------------------------------|
  315. | `I want a temperature sensor with OLED on ESP32` | Routes to Volt. Picks a board, validates the pins, returns ESPHome YAML and a wiring diagram.|
  316. | `Lights on at sunset, off at midnight` | Routes to Sage. Returns a Home Assistant automation in modern syntax. |
  317. | `Motion lights: sensor on ESP32, automation in HA` | Plans Volt then Sage. Writes the entity IDs once, both agents use them. |
  318. | `Python integration for the Acme cloud API, HACS ready`| Routes to Ada. Walks you through architecture and config flow. |
  319. | `Review this YAML for me` | Volt or Sage reads your config, runs validators, reports findings anchored to line numbers. |
  320. ---
  321. ## What Aurora helps you do
  322. - **Generate ESPHome firmware** that compiles, on a board that actually exists,
  323. with pins that are not reserved by USB or PSRAM.
  324. - **Write Home Assistant automations and dashboards** that reference entities
  325. the firmware side actually creates.
  326. - **Build Python custom integrations** that pass HACS validation and do not
  327. ship `datetime.now()` inside an async coroutine.
  328. - **Review configs you already have.** Paste existing YAML and Aurora flags
  329. every issue with line-number anchored fixes.
  330. - **Connect external APIs** (Tibber, SMHI, OpenWeatherMap, Spotify, and others)
  331. using verified patterns.
  332. ---
  333. ## Who this is for
  334. Aurora fits three kinds of work:
  335. - **First sensor, first automation, first time touching ESP32.** Aurora
  336. picks parts that exist, pins that work, and a board that has not been
  337. end-of-lifed. You get one working build and the reasoning behind it.
  338. After that, you can do the next one without asking.
  339. - **Existing install, dozens of automations, allergic to surprises.**
  340. Paste your YAML. Aurora checks it against your HA version and every
  341. entity in your setup, reports each issue with a line number and a
  342. paste-ready fix, and does not rewrite your file.
  343. - **Building something to ship to other people.** Volt knows the
  344. difference between a board that survives a botched OTA and one that
  345. needs a recovery jig. Ada knows what HACS reviewers will catch before
  346. you submit.
  347. ---
  348. ## How Aurora works
  349. ### Activate Aurora — two ways
  350. ```
  351. ┌─────────────────────────────────────────────────────────────┐
  352. │ Inline (one turn): │
  353. │ /aurora:aurora build a CO2 monitor on ESP32-S3 │
  354. │ │
  355. │ Two-step (separate turns): │
  356. │ 1) /aurora:aurora │
  357. │ → Aurora shows its banner and asks the opening │
  358. │ question. │
  359. │ 2) build a CO2 monitor on ESP32-S3 │
  360. └─────────────────────────────────────────────────────────────┘
  361. ```
  362. Both paths end up in the same routing flow. Re-running `/aurora:aurora`
  363. later in the same conversation skips the banner and just acknowledges
  364. that Aurora is already loaded — no version check, no re-greeting.
  365. ### Routing
  366. ```
  367. ┌─────────────────────────────────────────────────────────────┐
  368. │ Aurora (orchestrator) │
  369. │ Parses intent, picks the right specialist(s), │
  370. │ recommends a Claude model tier, opens a shared snapshot │
  371. │ if more than one specialist is involved. │
  372. └─────────────────────────────────────────────────────────────┘
  373. │
  374. ▼
  375. ┌─────────────────────────────────────────────────────────────┐
  376. │ Specialist (Volt for firmware in this case) │
  377. │ Loads the board profile (aurora/references/boards/). │
  378. │ Loads the component profile (aurora/references/ │
  379. │ components/). │
  380. │ Calls validators: pin, conflict, i2c-address, voltage, │
  381. │ ota-safety, version, entity-id, secrets. │
  382. │ If a validator fails, refuses to generate. Shows a fix. │
  383. │ If validators pass, returns YAML + wiring + calibration. │
  384. └─────────────────────────────────────────────────────────────┘
  385. ```
  386. When the project spans firmware plus automations plus a dashboard, the agents
  387. share a **project snapshot** written to your workspace as `aurora-project.json`.
  388. Single-agent (QUICK mode) tasks skip the snapshot so there is no overhead for
  389. small jobs. Multi-agent (DEEP mode) tasks use it like this:
  390. ```
  391. You: "Motion sensor on ESP32, automation in HA, with a dashboard tile"
  392. Volt creates: binary_sensor.living_room_motion
  393. Sage uses: binary_sensor.living_room_motion as trigger
  394. Iris places: binary_sensor.living_room_motion on the room view
  395. If Sage references an entity Volt did not produce, or if Iris cannot find
  396. the entity on the dashboard, Aurora raises a conflict instead of generating
  397. broken YAML. Conflicts surface to you, not silently to the next agent.
  398. ```
  399. ---
  400. ## What gets delivered
  401. Aurora does not paste code into chat and call it done. Every project produces a folder on disk with the working files plus a `README.md` you can hand to someone else.
  402. ### Hardware projects (Volt)
  403. ```
  404. bedroom-co2/
  405. ├── README.md ← project manual
  406. ├── bedroom-co2.yaml ← ESPHome firmware
  407. └── secrets.yaml.example ← WiFi + API key template
  408. ```
  409. The project README carries: what it does, BOM with estimated unit prices and a dated total, wiring with connection table and ASCII diagram, installation steps from flash to verified entities in Home Assistant, calibration procedures for the specific sensors used, troubleshooting for the three most likely failure points, and recovery instructions for when OTA goes wrong.
  410. For custom PCB or production runs the folder grows with `SCHEMATIC.md`, `PCB-NOTES.md`, and (for production) `MANUFACTURING.md`, `COST-ANALYSIS.md`, `CERTIFICATION.md`, `TEST-JIG.md`. Aurora produces text specifications, not KiCad binaries.
  411. ### Software projects (Sage, Ada, River, Iris)
  412. For automations (Sage), custom integrations (Ada), Node-RED flows (River), and dashboards (Iris), the project folder includes the working YAML / Python / JSON plus a `README.md` with agent-specific installation steps, troubleshooting, and recovery.
  413. Custom integrations (Ada) include the full `custom_components/<id>/` structure with `manifest.json`, `strings.json`, translations, and a HACS-ready repo layout (`hacs.json`, `LICENSE`, `.github/workflows/validate.yaml`) when requested.
  414. ### What you do not get
  415. Aurora does not produce KiCad files, gerbers, or PNG wiring images. Schematics ship as text with ASCII block diagrams that a human or PCB designer can rebuild in their preferred tool.
  416. The contract is enforced by Iron Law 8 in Volt's soul and Iron Law 3 in the four software-only specialists. Each agent verifies that every required file exists on disk before declaring delivery complete.
  417. ---
  418. ## Validation and safety
  419. Aurora ships **12 validators** that specialist agents must run before
  420. returning code, plus three supporting specs (a shared output format, a
  421. retroactive review protocol, and a board-selector helper). All files live
  422. in [`aurora/references/validators/`](./aurora/references/validators/).
  423. **Validators (block code generation on failure):**
  424. | Validator | Catches |
  425. |---------------------------------|------------------------------------------------------------------------------------------------------|
  426. | `pin-validator` | GPIO that does not exist on this board, reserved pins (USB, flash, PSRAM), strapping pins. |
  427. | `conflict-validator` | Two devices on the same GPIO, two pull-up sensors fighting. |
  428. | `i2c-address-validator` | BME280 + BMP280 collision at 0x76, reserved address ranges. |
  429. | `voltage-level-validator` | 5V sensor on a 3.3V board, missing level shifter, wrong shifter type. |
  430. | `ota-safety-validator` | YAML that would leave the board unrecoverable (e.g. disabling WiFi on a board without USB recovery). |
  431. | `version-validator` | References to features your ESPHome or HA version does not support. |
  432. | `entity-id-validator` | Automation that references an entity no integration produces. |
  433. | `secrets-validator` | API keys, OAuth tokens, or webhook URLs pasted as literals. |
  434. | `async-correctness-validator` | `datetime.now()`, `requests`, `time.sleep` in HA async code. |
  435. | `llm-config-validator` | Conversation agent pointed at the wrong provider, prompt template over the token budget. |
  436. | `node-red-syntax-validator` | Legacy node type names that silently fail to deploy on Node-RED 4.x. |
  437. | `unknown-component-validator` | A community component Aurora has not seen. Asks for source URL, version, docs. Refuses if you cannot answer. |
  438. **Supporting specs:**
  439. | Spec | Role |
  440. |---------------------------------|------------------------------------------------------------------------------------------------------|
  441. | `_tiered-errors` | Shared output format used by every validator above. |
  442. | `retroactive-yaml-review` | Protocol agents follow when you paste existing YAML and ask for review. |
  443. | `board-selector` | Helper that picks a board for your project requirements. |
  444. Every validator emits the same four-tier output:
  445. ```
  446. ❌ Problem (short):
  447. GPIO 19 cannot be used on ESP32-S3 DevKit C-1 while USB CDC is enabled.
  448. 📚 Explanation (medium):
  449. The ESP32-S3 routes USB D+/D- to GPIO 19/20. With usb_cdc: enabled,
  450. these pins are reserved and any assignment to them collides with USB.
  451. 🔧 Fix (concrete):
  452. Move the sensor to GPIO 8 (SDA) and GPIO 9 (SCL), the board's default
  453. I2C pins.
  454. 💡 Deeper (optional):
  455. You can set usb_cdc: false to free GPIO 19/20, but you lose USB serial
  456. console (only OTA-over-WiFi remains for log inspection).
  457. ```
  458. When this block fires, **the agent stops.** No YAML is written until the
  459. problem is resolved or you explicitly tell the agent to override. The fix line
  460. is concrete enough that you usually paste two lines into your config and rerun.
  461. **When validators pass,** you get a complete result: the YAML, a wiring
  462. diagram, the calibration procedure for the sensors involved, and a
  463. troubleshooting section. Not half-finished code that compiles but fails to
  464. boot.
  465. **Safety scope.** Smart home work touches mains electricity, batteries, locks,
  466. water, and heating. Aurora validates configuration against verified reference
  467. data, but it does not replace your judgement, your electrician, or your fuse
  468. box. See [DISCLAIMER.md](DISCLAIMER.md) for the full statement.
  469. ---
  470. ## Included skills
  471. Aurora is one plugin (`aurora@aurora-smart-home`). Inside it sits the
  472. `/aurora:aurora` orchestrator command plus six topic skills. The orchestrator
  473. routes requests across skills and across agents. The topic skills also
  474. activate automatically when you mention relevant keywords, so you can skip
  475. the orchestrator on quick tasks.
  476. | Skill | Activates on |
  477. |------------------------|---------------------------------------------------------------|
  478. | `esphome` | "ESPHome", "ESP32", "ESP8266", board names |
  479. | `home-assistant` | "automation", "blueprint", "automations.yaml" |
  480. | `ha-integration-dev` | "custom integration", "HACS", "custom_components" |
  481. | `node-red` | "Node-RED", "flow", "function node" |
  482. | `api-catalog` | Specific service names (Tibber, SMHI, OpenAI, etc.) |
  483. | `ha-dashboard-design` | "dashboard look", "card-mod", "Lovelace theme" |
  484. ## Meet the Aurora team
  485. <details>
  486. <summary><strong>Show all 21 agents</strong></summary>
  487. Aurora runs like a small smart home agency. 1 orchestrator + 20 named specialists across 7 departments. Each specialist has a defined domain, a soul (`aurora/souls/`), and a voice. Agents are not owned by a single skill, they are routed in by the orchestrator wherever their domain fits.
  488. 🏠 **Aurora** | Founder and orchestrator. *"Your home should work for you, locally, privately, without asking permission."*
  489. **Hardware department**
  490. - ⚡ **Volt** | ESP32/ESP8266/Shelly firmware + IR proxy. *"Board first, then we build."*
  491. - 📡 **Nano** | Matter, Thread, BLE, embedded protocols. *"Matter over Thread is the right call here. Let me explain why."*
  492. - 🎙️ **Echo** | Voice, audio, wake word, Assist pipeline. *"Let's make sure your voice pipeline is solid end to end."*
  493. - 🔋 **Watt** | Power budget, battery sizing, solar dimensioning. *"Before we spec the battery, what is the duty cycle?"*
  494. **Home Assistant department**
  495. - 🧙 **Sage** | YAML automations, blueprints, scripts, helpers. *"Automation, blueprint, or script? Each one has a different shape."*
  496. - ❤️ **Ada** | Python custom integrations, coordinators, config flows. *"This will fail in production. You need `dt_util.now()`."*
  497. - 🤖 **Mira** | LLM, AI, conversation agents. *"Are we responding to commands, or inferring intent?"*
  498. - 🌊 **River** | Node-RED visual automation flows. *"Map the flow first: trigger, condition, action."*
  499. - 🦄 **Iris** | Dashboard visual design. *"Imagine walking into the room. What do you want to know at a glance?"*
  500. **Field intelligence**
  501. - 🏪 **Atlas** | External API patterns, OAuth, community integrations. *"Someone has already solved this. Let me show you how the community does it."*
  502. **Quality desk**
  503. - 🐛 **Glitch** | Cross-skill debugging. *"Paste the full log. Not the part you think matters, all of it."*
  504. - ✅ **Probe** | QA, testing, validation. *"Looks right, but let us test the edge cases first."*
  505. - 🏡 **Vera** | WAF + hardware safety review. *"What happens when the motion sensor misses? Can someone turn the light on manually?"*
  506. - 🔬 **Lens** | Code review, security audit. *"Three things need fixing here. Not suggestions, these will cause incidents."*
  507. - 📖 **Manual** | Installation guides, troubleshooting docs. *"The firmware is done. Now let us make sure someone else can install it."*
  508. **Research library**
  509. - 🔭 **Scout** | Research, investigation. *"Give me a moment, I have seen this discussed somewhere."*
  510. - 📚 **Lore** | Documentation writing. *"The setup section assumes the user already has HACS installed."*
  511. **Operations**
  512. - 🔧 **Forge** | Deploy, Docker, server, backups. *"Before we update, do you have a full backup from today?"*
  513. - 🌐 **Grid** | Network, UniFi, firewall, VLAN. *"That device is probably on the wrong VLAN."*
  514. **Design studio**
  515. - 🎨 **Canvas** | Graphic design, UI beyond dashboards. *"The layout works but it has seven things asking for attention at once."*
  516. </details>
  517. ---
  518. ## Examples
  519. Complete, working projects live in [`examples/`](./examples/):
  520. | Example | What it builds |
  521. |------------------------------------------------------------------------|---------------------------------------------------------------|
  522. | [complete-smart-room](./examples/complete-smart-room/) | Full room with sensors, voice control, automations. |
  523. | [smart-greenhouse](./examples/smart-greenhouse/) | Automated irrigation, climate monitoring, grow lights. |
  524. | [smart-garage](./examples/smart-garage/) | Garage door control, car detection, safety features. |
  525. | [energy-monitor](./examples/energy-monitor/) | CT clamp power monitoring, cost tracking, alerts. |
  526. For how the skills connect across a multi-step project, see
  527. [SKILL-INTEGRATION.md](./SKILL-INTEGRATION.md).
  528. ---
  529. ## Updating
  530. Claude Code does not auto-update plugins by default. Aurora ships new boards,
  531. sensors, and validators regularly.
  532. ```
  533. # Inside Claude Code (refreshes every installed plugin)
  534. /reload-plugins
  535. # From your terminal (targets aurora only)
  536. claude plugin update aurora@aurora-smart-home
  537. ```
  538. Then restart Claude Code so the new files load.
  539. **Enable auto-update once and forget:**
  540. 1. Run `/plugin` to open the plugin manager.
  541. 2. Open the **Marketplaces** tab.
  542. 3. Pick `aurora-smart-home`.
  543. 4. Choose **Enable auto-update**.
  544. Note: the slash command `/plugin update <name>` does not accept arguments.
  545. Use `/reload-plugins` or the CLI form above.
  546. ---
  547. ## Troubleshooting
  548. | Symptom | First thing to check |
  549. |--------------------------------------|-----------------------------------------------------------------------|
  550. | `/aurora:aurora` not found | Restart Claude Code after install. Then `/reload-plugins`. |
  551. | Validator never fires | Confirm your request triggers a specialist (say "ESPHome", "automation"). |
  552. | Aurora invents a community component | It should not. If it does, that is a bug. Open an issue. |
  553. | Plugin feels out of date | `claude plugin update aurora@aurora-smart-home`, then `/reload-plugins`. |
  554. Full guide: [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
  555. ---
  556. ## Changelog
  557. Version history lives in [CHANGELOG.md](./CHANGELOG.md).
  558. The roadmap lives in [ROADMAP.md](./ROADMAP.md).
  559. ---
  560. ## Contributing
  561. Issues and pull requests welcome. Start with [CONTRIBUTING.md](./CONTRIBUTING.md)
  562. for the contribution workflow. Adding boards or components goes through
  563. [aurora/references/](./aurora/references/) and must pass the pytest suite
  564. (`pytest aurora/tests/`).
  565. ---
  566. ## License
  567. MIT. See [LICENSE](LICENSE).
  568. ---
  569. ## Credits
  570. Aurora's agent personas are inspired by the people building the Open Home.
  571. | Agent | Inspired by |
  572. |--------------------|-----------------------------------------------------------------------------------|
  573. | **Aurora** | Otto Privacyhaus, believes your home should work without asking the cloud. |
  574. | **Ada** + **Lens** | Hendrik Nomerge, your PR is not ready, he knows, he will tell you. |
  575. | **Atlas** | Lars Hacsworth, built the store everyone uses to share their builds. |
  576. | **Iris** + **Lore**| Penelope Crowwhisperer, tamer of crows, bridge between humans and their homes. |
  577. | **Mira** | François Backlogeau, has opinions about roadmaps, very French ones. |
  578. ---
  579. ## Get started in 30 seconds
  580. In Claude Code 2.1.275 or later, install Aurora with:
  581. ```text
  582. /plugin install aurora --marketplace tonylofgren/aurora-smart-home
  583. ```
  584. Confirm the installation, then run `/aurora:aurora`.
  585. Using Codex or an older Claude Code? See the [installation guide](#quick-start).
  586. Then describe what you want to build.
  587. ---
  588. **Aurora helps you work with Home Assistant.** Home Assistant's core development is funded by [Nabu Casa](https://www.nabucasa.com). If your home runs on HA, please consider supporting them. Aurora is an independent community project, not affiliated with, endorsed by, or funded by Nabu Casa, the Open Home Foundation, or Anthropic. Agent personas are fictional.
  589. ---
  590. ## Contact
  591. Questions, build ideas, or want to share a project? Reach out on Instagram:
  592. [@roligaprojekt](https://www.instagram.com/roligaprojekt).
  593. Bug reports and feature requests: open a
  594. [GitHub issue](https://github.com/tonylofgren/aurora-smart-home/issues).
  595. ---
  596. Created for use with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) by Anthropic.

Ratings and comments

Sign in to rate this skill.

Sign in

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