Skip to content
Back to search

home-assistant-vibecode-agent

Home Assistant MCP server agent. Enable Claude Code, Cursor, VS Code or any MCP-enabled IDE to help you vibe-code and manage Home Assistant: create and debug automations, design dashboards, tweak themes, modify configs, and deploy changes using natural language

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/coolver--home-assistant-vibecode-agent/badge.svg)](/listings/coolver--home-assistant-vibecode-agent)

HTML

<a href="/listings/coolver--home-assistant-vibecode-agent"><img src="/api/listings/coolver--home-assistant-vibecode-agent/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.

Option A: Home Assistant Add-on (default, recommended)

**For users running Home Assistant OS or Supervised installation.**

This is the standard deployment — the agent runs as a managed add-on inside Home Assistant with full access to Supervisor API.

1. Add Repository

Open your **Home Assistant UI** (usually http://homeassistant.local:8123):

1. Go to **Settings** → **Add-ons** → **Add-on Store** → **⋮** → **Repositories** (usually http://homeassistant.local:8123/hassio/dashboard ) 2. Add: `https://github.com/coolver/home-assistant-vibecode-agent` 3. Click **Add**

2. Install and Start Add-on

Still in **Home Assistant UI**:

1. Refresh the page 2. Find **HA Vibecode Agent** → Click **INSTALL** 3. Wait for installation to complete 4. Enable → **Start on boot: ON** → and push **START** button 5. **Wait for startup** (~10 seconds) 6. Click **"Open Web UI"** button

You'll see this interface:

<p align="center"> </p>

7. Click the **Cursor** or **VS Code** tab (depending on which IDE you want to use with Home Assistant) and **follow the setup instructions**. You'll need to install and configure Cursor or VS Code so they can connect to the HA Agent via the MCP protocol.

8. That's it — **you're ready to start** working with your Home Assistant scripts, automations and dashboards using AI.

If you find this project useful and want to support its development, **please consider giving it a [GitHub Star](https://github.com/Coolver/home-assistant-vibecode-agent) ⭐**

[YouTube Installation guide: how to install the Home Assistant Cursor Agent](https://youtu.be/RZNkNZnhMrc)

---

Option B: Standalone Docker (Proxmox / Docker / NAS)

**For users running Home Assistant Container without Supervisor** (e.g., in Proxmox LXC/VM, Synology NAS, or plain Docker Compose).

The agent runs as a separate Docker container alongside your Home Assistant instance and connects via a Long-Lived Access Token.

Prerequisites

- Home Assistant running and accessible over the network - **Long-Lived Access Token** — create one in HA UI: **Profile** (bottom-left) → **Long-Lived Access Tokens** → **Create Token** - Docker and Docker Compose installed on the host

1. Clone the repository

git clone https://github.com/Coolver/home-assistant-vibecode-agent.git
cd home-assistant-vibecode-agent

2. Configure environment

cp .env.example .env

Edit `.env` with your values:

HA_URL=http://192.168.1.100:8123
HA_TOKEN=your_long_lived_access_token_here
HA_CONFIG_PATH=/path/to/homeassistant/config

3. Start the agent

docker compose -f docker-compose.standalone.yml up -d

4. Get the API key

The agent auto-generates an API key on first start. View it in the logs:

docker compose -f docker-compose.standalone.yml logs | grep "API Key"

Or read it directly from the config directory:

cat /path/to/homeassistant/config/.ha_cursor_agent_key

5. Configure your IDE

The agent is now available at `http://<host-ip>:8099`. Configure your MCP client (Cursor, VS Code, etc.) to connect using the API key from step 4.

---

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 · 436 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # HA Vibecode Agent
  2. [![Version](https://img.shields.io/badge/version-2.10.50-blue.svg)](https://github.com/Coolver/home-assistant-vibecode-agent)
  3. [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  4. [![MCP Package](https://img.shields.io/npm/v/@coolver/home-assistant-mcp?label=MCP%20Package)](https://www.npmjs.com/package/@coolver/home-assistant-mcp)
  5. [![Landing Page](https://img.shields.io/badge/Landing%20Page-coolver.github.io-blueviolet)](https://coolver.github.io/home-assistant-vibecode-agent/)
  6. **Let AI build your Home Assistant automations – or act as your DevOps for the ones you write by hand. Just describe what you need in natural language. 🏠🤖**
  7. You describe your goal → AI inspects your Home Assistant → designs a custom solution → and deploys it on-board automatically. 🚀
  8. And if you prefer to handcraft your automations and scripts yourself, the agent can simply act as your DevOps and extra pair of hands: quickly uploading your changes, running tests, and analyzing logs on demand. **You stay in control and decide how much you delegate to AI and how deep it should go.**
  9. Transform the way you manage your smart home. This agent enables **Claude Code**, **Cursor**, **Visual Studio Code (VS Code)**, or any **MCP-enabled IDE** to:
  10. - 📝 Analyze your Home Assistant configuration, entities, and devices
  11. - 🏗️ Create intelligent automations, scripts, and complete systems — including Home Assistant helpers that can be fully managed programmatically
  12. - 🎨 Design and customize UI dashboards with full control over cards, layouts, and styling
  13. - 🖌️ Create and tweak themes for a personalized UI
  14. - 🔄 Safely deploy changes with automatic Git-based versioning
  15. - 🔍 Monitor and troubleshoot your setup through log analysis
  16. - 📦 Install and manage HACS integrations and custom repositories
  17. No more manual YAML editing or searching through documentation - just describe what you want in natural language!
  18. **Real example:** User says *"Install smart climate control"* → AI analyzes 7 TRVs, creates 10 automations + 9 helpers + 10 sensors + 5 scripts, deploys everything, and it just works!
  19. https://github.com/user-attachments/assets/0df48019-06c0-48dd-82ad-c7fe0734ddb3
  20. **Full YouTube Demo:**
  21. - [How to control Home Assistant from Cursor](https://youtu.be/xocbWonWdoc)
  22. ## What's new in 2.10.50
  23. This one is mostly thanks to people who sent pull requests and wrote issues. Pair it with MCP client **3.2.32**.
  24. The setup page with the API key is only available through Home Assistant Ingress now, and the open CORS header is gone. Checkpoints save the edits as they happen, so a forgotten "end checkpoint" no longer throws the work away. `secrets.yaml`, key files, and Home Assistant's auth and config-entry storage are blocked from the file tools unless you turn that back on. Failed Home Assistant commands are reported as failures. Extra keys on an automation are kept. Backups and cache files are no longer copied into the shadow git.
  25. The assistant can also put an automation or script in a category, read the real Home Assistant Core log, get the data back from a service such as a weather forecast, install a HACS repository from the editor (that call used to fail every time), and remove one HACS card without uninstalling HACS. Dialogs that used to be UI-only, such as changing a switch into a light or configuring an integration, can be driven step by step.
  26. Thank you to [@CrazyCoder](https://github.com/CrazyCoder), [@arno82](https://github.com/arno82), [@Thijs226](https://github.com/Thijs226), [@telcopro](https://github.com/telcopro), [@olomouckyorel](https://github.com/olomouckyorel), [@eyal0](https://github.com/eyal0), [@GammelSami](https://github.com/GammelSami), [@gvillo](https://github.com/gvillo), and [@mnestrud](https://github.com/mnestrud). The longer note, with a line for each report, is in the changelog. That is the text Home Assistant shows as the add-on update info.
  27. ---
  28. ## 🎯 What is this?
  29. **HA Vibecode Agent** is a service that exposes a safe REST API and toolset, allowing AI assistants (Claude Code, Cursor, VS Code, Antigravity, and any MCP-enabled IDE) to safely work *with* your Home Assistant instead of just generating YAML in the dark.
  30. It supports two deployment modes:
  31. | Mode | For whom | How it runs |
  32. |------|----------|-------------|
  33. | **Supervisor (Add-on)** | Home Assistant OS / Supervised | Installed via HA Add-on Store (default) |
  34. | **Standalone (Docker)** | HA Container in Docker / Proxmox / NAS | Runs as a separate Docker container |
  35. Both modes provide the same core functionality. The only difference: **Add-on management** (install/uninstall/restart add-ons) requires the Supervisor and is not available in standalone mode.
  36. ---
  37. ### 🚀 How is this different from other MCP modules for Home Assistant?
  38. # Home Assistant Agent + MCP Server
  39. Most MCP integrations for Claude, Cursor, VS Code or Antigravity run only on your local machine and talk to Home Assistant over SSH, sometimes with the REST API.
  40. For serious Home Assistant work, that is not enough.
  41. Home Assistant is not just a set of YAML files. It exposes internal APIs, runtime state, entities, services and capabilities that are much easier and safer to access from inside Home Assistant itself.
  42. SSH-based integrations often force the AI to generate and run temporary helper scripts on every request. Since those scripts can change every time, the result is hard to predict, hard to repeat and risky to rely on.
  43. This project uses a different architecture.
  44. ## Architecture
  45. The project is split into two modules:
  46. ### Home Assistant Agent
  47. Runs inside, or alongside, Home Assistant.
  48. It has native access to relevant APIs, files, entities, services and runtime state, and exposes a safe, well-defined interface for external tools.
  49. ### Home Assistant MCP Server
  50. Runs on your computer alongside your AI IDE, such as Cursor, VS Code, Claude Desktop or Antigravity.
  51. It talks to the Agent over a controlled API instead of relying on SSH hacks.
  52. ## Why this design
  53. This makes Home Assistant automation faster, safer, more predictable and repeatable.
  54. The AI IDE gets exactly the actions and data it needs through a stable API, instead of constantly inventing ad-hoc scripts.
  55. It also improves context efficiency.
  56. Instead of loading huge YAML files, full entity dumps, logs or generated scripts into the prompt, the Agent can return only the relevant context: selected entities, services, automation fragments, validation results, errors or structured summaries.
  57. The result is less noise, fewer tokens, fewer wrong assumptions and more reliable edits.
  58. ## In short
  59. The MCP server gives your AI IDE a standard way to talk to Home Assistant.
  60. The Agent gives it safe, native access to Home Assistant itself.
  61. **Together, they replace fragile SSH-based scripting with a stable, structured and context-efficient automation layer**
  62. ---
  63. ## ⚡ Installation (5 minutes)
  64. ### Option A: Home Assistant Add-on (default, recommended)
  65. **For users running Home Assistant OS or Supervised installation.**
  66. This is the standard deployment — the agent runs as a managed add-on inside Home Assistant with full access to Supervisor API.
  67. #### 1. Add Repository
  68. Open your **Home Assistant UI** (usually http://homeassistant.local:8123):
  69. 1. Go to **Settings** → **Add-ons** → **Add-on Store** → **⋮** → **Repositories** (usually http://homeassistant.local:8123/hassio/dashboard )
  70. 2. Add: `https://github.com/coolver/home-assistant-vibecode-agent`
  71. 3. Click **Add**
  72. #### 2. Install and Start Add-on
  73. Still in **Home Assistant UI**:
  74. 1. Refresh the page
  75. 2. Find **HA Vibecode Agent** → Click **INSTALL**
  76. 3. Wait for installation to complete
  77. 4. Enable → **Start on boot: ON** → and push **START** button
  78. 5. **Wait for startup** (~10 seconds)
  79. 6. Click **"Open Web UI"** button
  80. You'll see this interface:
  81. <p align="center">
  82. <img src=".github/images/ingress-panel.jpg" alt="HA Vibecode Agent Ingress Panel" width="700">
  83. </p>
  84. 7. Click the **Cursor** or **VS Code** tab (depending on which IDE you want to use with Home Assistant) and **follow the setup instructions**. You'll need to install and configure Cursor or VS Code so they can connect to the HA Agent via the MCP protocol.
  85. 8. That's it — **you're ready to start** working with your Home Assistant scripts, automations and dashboards using AI.
  86. If you find this project useful and want to support its development, **please consider giving it a [GitHub Star](https://github.com/Coolver/home-assistant-vibecode-agent) ⭐**
  87. [YouTube Installation guide: how to install the Home Assistant Cursor Agent](https://youtu.be/RZNkNZnhMrc)
  88. ---
  89. ### Option B: Standalone Docker (Proxmox / Docker / NAS)
  90. **For users running Home Assistant Container without Supervisor** (e.g., in Proxmox LXC/VM, Synology NAS, or plain Docker Compose).
  91. The agent runs as a separate Docker container alongside your Home Assistant instance and connects via a Long-Lived Access Token.
  92. #### Prerequisites
  93. - Home Assistant running and accessible over the network
  94. - **Long-Lived Access Token** — create one in HA UI: **Profile** (bottom-left) → **Long-Lived Access Tokens** → **Create Token**
  95. - Docker and Docker Compose installed on the host
  96. #### 1. Clone the repository
  97. ```bash
  98. git clone https://github.com/Coolver/home-assistant-vibecode-agent.git
  99. cd home-assistant-vibecode-agent
  100. ```
  101. #### 2. Configure environment
  102. ```bash
  103. cp .env.example .env
  104. ```
  105. Edit `.env` with your values:
  106. ```env
  107. HA_URL=http://192.168.1.100:8123
  108. HA_TOKEN=your_long_lived_access_token_here
  109. HA_CONFIG_PATH=/path/to/homeassistant/config
  110. ```
  111. #### 3. Start the agent
  112. ```bash
  113. docker compose -f docker-compose.standalone.yml up -d
  114. ```
  115. #### 4. Get the API key
  116. The agent auto-generates an API key on first start. View it in the logs:
  117. ```bash
  118. docker compose -f docker-compose.standalone.yml logs | grep "API Key"
  119. ```
  120. Or read it directly from the config directory:
  121. ```bash
  122. cat /path/to/homeassistant/config/.ha_cursor_agent_key
  123. ```
  124. #### 5. Configure your IDE
  125. The agent is now available at `http://<host-ip>:8099`. Configure your MCP client (Cursor, VS Code, etc.) to connect using the API key from step 4.
  126. ---
  127. ## 🤖 Using with AI IDE (Cursor, VS Code etc)
  128. This agent enables **AI IDE to autonomously manage your Home Assistant** through natural language - no manual copy-pasting needed!
  129. ### ⚠️ Important Disclaimer
  130. **This tool is designed for experienced Home Assistant users who understand what they're doing.**
  131. - ✅ **Always review changes** before applying them to production systems
  132. - ⚠️ **AI can accidentally break your configuration** if given incorrect instructions or outdated information
  133. - 💾 **Git versioning is enabled by default** - all changes are backed up and can be rolled back
  134. - 🔄 **Test in a safe environment first** if you're new to AI-driven automation
  135. - 📖 **Verify syntax and compatibility** with your Home Assistant version
  136. **Use at your own risk. The automatic backup system minimizes risk but doesn't eliminate it.**
  137. ### Start Using
  138. Once connected, just describe what you want in natural language:
  139. ```
  140. Show me all my climate entities and their current states
  141. ```
  142. ```
  143. Analyze my automations and suggest optimizations
  144. ```
  145. ```
  146. Create a smart lighting automation for movie mode
  147. ```
  148. AI will autonomously read your configuration, create components, and deploy everything automatically!
  149. **That's it!** AI IDE will use the MCP protocol to communicate with your Home Assistant.
  150. **Learn more:** [MCP Home Assistant on GitHub](https://github.com/Coolver/home-assistant-mcp) | [NPM Package](https://www.npmjs.com/package/@coolver/home-assistant-mcp)
  151. ### Real-World Examples
  152. **Build Smart Climate Control:**
  153. ```
  154. Install a smart climate control system for my TRV radiators.
  155. Analyze my current devices, create automations for efficient heating
  156. with predictive shutdown, buffer radiators, and adaptive cooldowns.
  157. Set up monitoring sensors and dashboard.
  158. ```
  159. **AI will autonomously:**
  160. - Detect all your TRV entities by analyzing Home Assistant
  161. - Create 10+ automations for intelligent heating control
  162. - Add 9 input helpers for system state management
  163. - Generate 10 template sensors for monitoring
  164. - Create 5 scripts for boiler and buffer control
  165. - Build Lovelace dashboard with all metrics
  166. - Test and deploy everything
  167. - **All tailored to YOUR specific TRVs and configuration!**
  168. **Optimize Existing System:**
  169. ```
  170. My heating wastes energy. Analyze my current climate automations
  171. and optimize for efficiency while maintaining comfort.
  172. ```
  173. **Debug Issues:**
  174. ```
  175. My bedroom lights automation isn't working. Check the logs,
  176. find the problem, and fix it.
  177. ```
  178. **Stop writing YAML manually! Just describe what you want.** 🚀
  179. ---
  180. ## 📚 API Documentation
  181. For complete API documentation, authentication details, and usage examples, see **[DEVELOPMENT.md](DEVELOPMENT.md)**.
  182. **Quick access:**
  183. - **Swagger UI:** `http://homeassistant.local:8099/docs` (when installed)
  184. - **ReDoc:** `http://homeassistant.local:8099/redoc` (when installed)
  185. ---
  186. ## 🔍 Monitoring
  187. ### Check Agent Health
  188. ```bash
  189. # No auth required for health check
  190. curl http://homeassistant.local:8099/api/health
  191. ```
  192. **Example response:**
  193. ```json
  194. {
  195. "status": "healthy",
  196. "version": "2.0.1"
  197. }
  198. ```
  199. ### View Agent Logs
  200. ```bash
  201. curl -H "Authorization: Bearer YOUR_AGENT_KEY" \
  202. http://homeassistant.local:8099/api/logs/?limit=50
  203. ```
  204. ### View Backup History
  205. ```bash
  206. curl -H "Authorization: Bearer YOUR_AGENT_KEY" \
  207. http://homeassistant.local:8099/api/backup/history
  208. ```
  209. ---
  210. ## 🛡️ Security
  211. ### Safety Features
  212. - ✅ **Path validation** - Cannot access files outside `/config`
  213. - ✅ **Authentication required** - All endpoints (except health) require token
  214. - ✅ **Automatic backups** - Git commits before modifications with meaningful commit messages
  215. - ✅ **Rollback capability** - Restore any previous state
  216. - ✅ **Configuration validation** - Check before applying
  217. - ✅ **Audit logs** - Track all operations
  218. ### Best Practices
  219. 1. **Always backup** before major changes
  220. 2. **Check config** before reloading
  221. 3. **Review logs** after operations
  222. 4. **Use rollback** if something breaks
  223. 5. **Test in dev environment** first
  224. ---
  225. ## 🔧 Development
  226. For development setup, project structure, API documentation, and local development instructions, see **[DEVELOPMENT.md](DEVELOPMENT.md)**.
  227. ## 🤝 Contributing
  228. Contributions are welcome! If you'd like to contribute:
  229. 1. Fork the repository
  230. 2. Create a feature branch
  231. 3. Make your changes
  232. 4. Submit a pull request
  233. For detailed contribution guidelines, see **[CONTRIBUTING.md](CONTRIBUTING.md)**.
  234. ---
  235. ## 🐛 Troubleshooting
  236. ### "spawn npx ENOENT" error (Claude Code / Cursor / VS Code / Other IDE Console)
  237. This error means Node.js is not installed or not found in your system PATH.
  238. Solution: Install Node.js (v20.0.0 or higher; Node.js 24 LTS recommended) on the computer where Cursor is running:
  239. Download and install Node.js from https://nodejs.org
  240. Restart Cursor completely after installation
  241. Verify installation by running node --version in a terminal
  242. Important: Node.js must be installed on your computer (where Cursor runs), not on the Home Assistant server.
  243. ### Add-on won't start
  244. **Check logs:** Supervisor → HA Vibecode Agent → Logs
  245. Common issues:
  246. - Port 8099 already in use
  247. - Invalid configuration
  248. - Missing permissions
  249. ### Standalone container won't start
  250. **Check logs:** `docker compose -f docker-compose.standalone.yml logs`
  251. Common issues:
  252. - `HA_URL` not set or unreachable
  253. - `HA_TOKEN` invalid or expired — regenerate in HA UI → Profile → Long-Lived Access Tokens
  254. - Config volume not mounted correctly — verify `HA_CONFIG_PATH` in `.env`
  255. ### API returns 401 Unauthorized
  256. - Check Agent Key is correct
  257. - Regenerate key if needed: Settings → Add-ons → HA Vibecode Agent → Open Web UI (add-on mode), or read from `/config/.ha_cursor_agent_key` (standalone mode)
  258. - Ensure Authorization header is present
  259. - Format: `Authorization: Bearer YOUR_AGENT_KEY`
  260. ### File operations fail
  261. - Check file paths are relative to `/config`
  262. - Ensure files exist for read/delete operations
  263. - Check YAML syntax for parse errors
  264. ### Git versioning not working
  265. - Git versioning is always enabled in shadow repository (`/config/ha_vibecode_git`)
  266. - Check `git_versioning_auto` setting for auto/manual commit mode
  267. - View logs for Git errors
  268. - Ensure `/config` is writable
  269. ## 💬 Support
  270. - 🐛 **Issues:** [GitHub Issues](https://github.com/Coolver/home-assistant-vibecode-agent/issues)
  271. - 💡 **Discussions:** [GitHub Discussions](https://github.com/Coolver/home-assistant-vibecode-agent/discussions)
  272. ---
  273. ## 📜 License
  274. MIT License - See LICENSE file
  275. ---
  276. **Ready to give your AI full control of Home Assistant? Install now!** 🚀

Ratings and comments

Sign in to rate this skill.

Sign in

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