HA Vibecode Agent
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. 🏠🤖
You describe your goal → AI inspects your Home Assistant → designs a custom solution → and deploys it on-board automatically. 🚀
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.
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:
- 📝 Analyze your Home Assistant configuration, entities, and devices
- 🏗️ Create intelligent automations, scripts, and complete systems — including Home Assistant helpers that can be fully managed programmatically
- 🎨 Design and customize UI dashboards with full control over cards, layouts, and styling
- 🖌️ Create and tweak themes for a personalized UI
- 🔄 Safely deploy changes with automatic Git-based versioning
- 🔍 Monitor and troubleshoot your setup through log analysis
- 📦 Install and manage HACS integrations and custom repositories
No more manual YAML editing or searching through documentation - just describe what you want in natural language!
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!
https://github.com/user-attachments/assets/0df48019-06c0-48dd-82ad-c7fe0734ddb3
Full YouTube Demo:
🎯 What is this?
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.
It supports two deployment modes:
| Mode | For whom | How it runs | |------|----------|-------------| | Supervisor (Add-on) | Home Assistant OS / Supervised | Installed via HA Add-on Store (default) | | Standalone (Docker) | HA Container in Docker / Proxmox / NAS | Runs as a separate Docker container |
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.
🚀 How is this different from other MCP modules for Home Assistant?
Home Assistant Agent + MCP Server
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.
For serious Home Assistant work, that is not enough.
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.
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.
This project uses a different architecture.
Architecture
The project is split into two modules:
Home Assistant Agent
Runs inside, or alongside, Home Assistant.
It has native access to relevant APIs, files, entities, services and runtime state, and exposes a safe, well-defined interface for external tools.
Home Assistant MCP Server
Runs on your computer alongside your AI IDE, such as Cursor, VS Code, Claude Desktop or Antigravity.
It talks to the Agent over a controlled API instead of relying on SSH hacks.
Why this design
This makes Home Assistant automation faster, safer, more predictable and repeatable.
The AI IDE gets exactly the actions and data it needs through a stable API, instead of constantly inventing ad-hoc scripts.
It also improves context efficiency.
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.
The result is less noise, fewer tokens, fewer wrong assumptions and more reliable edits.
In short
The MCP server gives your AI IDE a standard way to talk to Home Assistant.
The Agent gives it safe, native access to Home Assistant itself.
Together, they replace fragile SSH-based scripting with a stable, structured and context-efficient automation layer
⚡ Installation (5 minutes)
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):
- Go to Settings → Add-ons → Add-on Store → ⋮ → Repositories (usually http://homeassistant.local:8123/hassio/dashboard )
- Add:
https://github.com/coolver/home-assistant-vibecode-agent - Click Add
2. Install and Start Add-on
Still in Home Assistant UI:
- Refresh the page
- Find HA Vibecode Agent → Click INSTALL
- Wait for installation to complete
- Enable → Start on boot: ON → and push START button
- Wait for startup (~10 seconds)
- Click "Open Web UI" button
You'll see this interface:
-
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.
-
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 ⭐
YouTube Installation guide: how to install the Home Assistant Cursor Agent
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.
🤖 Using with AI IDE (Cursor, VS Code etc)
This agent enables AI IDE to autonomously manage your Home Assistant through natural language - no manual copy-pasting needed!
⚠️ Important Disclaimer
This tool is designed for experienced Home Assistant users who understand what they're doing.
- ✅ Always review changes before applying them to production systems
- ⚠️ AI can accidentally break your configuration if given incorrect instructions or outdated information
- 💾 Git versioning is enabled by default - all changes are backed up and can be rolled back
- 🔄 Test in a safe environment first if you're new to AI-driven automation
- 📖 Verify syntax and compatibility with your Home Assistant version
Use at your own risk. The automatic backup system minimizes risk but doesn't eliminate it.
Start Using
Once connected, just describe what you want in natural language:
Show me all my climate entities and their current states
Analyze my automations and suggest optimizations
Create a smart lighting automation for movie mode
AI will autonomously read your configuration, create components, and deploy everything automatically!
That's it! AI IDE will use the MCP protocol to communicate with your Home Assistant.
Learn more: MCP Home Assistant on GitHub | [NPM Package](https://www.npmjs.com/package/@coolver