Skip to content

Commit 51488e4

Browse files
authored
Refactor README to streamline features and installation
Remove sections on analysis, building intelligence, dashboards, safe operations, and community extensions from the README. Update installation section and add new features.
1 parent e68aa29 commit 51488e4

1 file changed

Lines changed: 2 additions & 239 deletions

File tree

README.md

Lines changed: 2 additions & 239 deletions
Original file line numberDiff line numberDiff line change
@@ -47,55 +47,6 @@ Both modes provide the same core functionality. The only difference: **Add-on ma
4747

4848
---
4949

50-
### 🔍 Analyze your setup
51-
52-
✅ Read your full configuration — entities, automations, scripts, helpers
53-
✅ Understand your devices — capabilities, relations, and usage patterns
54-
✅ Learn existing logic — analyze how your current automations and scripts behave
55-
56-
---
57-
58-
### 🏗️ Build intelligence
59-
60-
✅ Create complete systems — multiple interconnected automations in seconds
61-
✅ Generate helpers and sensors — tailored to your actual setup and needs
62-
✅ Write optimized scripts — based on real entities, areas, and devices
63-
✅ Refactor existing logic — improve or merge automations instead of starting from scratch
64-
65-
---
66-
67-
### 📊 Dashboards & UI
68-
69-
✅ Create and update Lovelace dashboards — fully programmatically
70-
✅ Add, remove, or rearrange cards — stat, graphs, history, custom cards, and more
71-
✅ Control layouts and views — organize rooms, areas, and scenarios
72-
✅ Design and tweak themes — colors, typography, and styles for a personalized UI
73-
74-
---
75-
76-
### 🔒 Safe operations
77-
78-
✅ Git-based versioning — every change is tracked with meaningful commit messages
79-
✅ Human-readable commits — AI explains *what* changed and *why*
80-
✅ Configuration validation — test before apply to reduce breaking changes
81-
✅ One-click rollback — revert to a previous state if something goes wrong
82-
✅ Activity log — full audit trail of what the agent did and when
83-
84-
---
85-
86-
### 📦 Extend with the community
87-
88-
✅ Install and configure HACS — unlock 1000+ community integrations
89-
✅ Search repositories — themes, plugins, custom components, dashboards
90-
✅ Install integrations — one-command setup for new HACS components
91-
✅ Keep things fresh — update all HACS repositories from a single place
92-
93-
---
94-
95-
**Result:**
96-
You describe your goal → AI inspects your Home Assistant → designs a custom solution → and deploys it on-board automatically. 🚀
97-
98-
9950
### 🚀 How is this different from other MCP modules for Home Assistant?
10051

10152
Most MCP integrations I've seen for Claude, Cursor, VS Code or Antigravity work only on your local machine and talk to Home Assistant over SSH and sometimes the REST API.
@@ -124,79 +75,7 @@ Your AI IDE gets exactly the actions and data it needs — through a stable API
12475

12576
---
12677

127-
## 🌟 Features
128-
129-
### 🏠 Home Assistant Integration
130-
- Full access to HA REST API and WebSocket
131-
- List all entities and their states
132-
- Call any HA service
133-
- Reload components (automations, scripts, templates)
134-
- Check configuration validity
135-
- Real-time state monitoring
136-
137-
### 📊 Dashboards & Themes
138-
- Create and update Lovelace dashboards programmatically
139-
- Add, remove, and rearrange cards (stat, graphs, history, custom cards, etc.)
140-
- Manage views, layouts, and groups for rooms and areas
141-
- Create and tweak themes for fully customized UI appearance
142-
- Safely adjust dashboards and themes through AI-driven operations
143-
144-
### 📁 File Management
145-
- List, read, write, append, delete files
146-
- Automatic backup before modifications
147-
- YAML parsing and validation
148-
- Safe path handling (restricted to `/config`)
149-
150-
### 🔧 Component Management
151-
- Create/Delete Input Helpers (boolean, text, number, datetime, select)
152-
- Create/Delete Automations
153-
- Create/Delete Scripts
154-
- Automatic reload after changes
155-
156-
### 💾 Git Versioning
157-
- Automatic commit on every change with meaningful commit messages
158-
- AI-generated descriptive messages explaining what and why changed
159-
- Backup history (up to 30 commits, configurable)
160-
- Automatic cleanup of old commits to prevent repository bloat
161-
- **View change history** – ask AI to show recent commits with meaningful messages
162-
- **Easy rollback** – ask AI to rollback to any previous version by description or commit hash
163-
- View diffs between versions
164-
- Commit messages include operation context (e.g., "Add automation: Control lights when motion detected")
165-
166-
**Example AI interactions:**
167-
- *"Show me the last 10 changes to my configuration"* → AI displays commit history with meaningful messages
168-
- *"Something broke! Roll back to the version from yesterday"* → AI finds and restores previous version
169-
- *"What changed in the last commit?"* → AI shows detailed diff
170-
- *"Roll back to when I added the motion sensor automation"* → AI finds and restores that specific commit
171-
172-
### 📡 Monitoring & Troubleshooting
173-
- Agent logs API with filtering
174-
- Operation history
175-
- Real-time status
176-
- Health check endpoint
177-
- System monitoring and analysis
178-
179-
### 🔌 Add-on Management *(Supervisor mode only)*
180-
**Complete add-on lifecycle management – install, configure, and control services!**
181-
- Install/uninstall add-ons (Zigbee2MQTT, Node-RED, ESPHome, etc.)
182-
- Configure add-on options
183-
- Start/stop/restart add-ons
184-
- Monitor add-on logs
185-
- Update add-ons
186-
- Powered by Supervisor API
187-
188-
### 📦 HACS Management
189-
**Complete HACS integration via WebSocket – browse 1000+ custom integrations!**
190-
- Install HACS automatically from GitHub
191-
- Search repositories by name, author, or category
192-
- Install integrations, themes, and plugins
193-
- Update all installed repositories
194-
- View repository details (stars, versions, authors)
195-
- Powered by persistent WebSocket connection
196-
197-
---
198-
199-
## ⚡ Installation
78+
## ⚡ Installation (5 minutes)
20079

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

@@ -296,21 +175,6 @@ cat /path/to/homeassistant/config/.ha_cursor_agent_key
296175

297176
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.
298177

299-
#### Feature availability in standalone mode
300-
301-
| Feature | Standalone | Add-on |
302-
|---------|:----------:|:------:|
303-
| File management (read/write/list) |||
304-
| Automations (CRUD) |||
305-
| Scripts (CRUD) |||
306-
| Dashboards & themes |||
307-
| Entities & states |||
308-
| Helpers |||
309-
| Git versioning & rollback |||
310-
| HACS management (WebSocket) |||
311-
| System logs & logbook |||
312-
| **Add-on management** |||
313-
314178
---
315179

316180
## 🤖 Using with AI IDE (Cursor, VS Code etc)
@@ -383,19 +247,6 @@ My bedroom lights automation isn't working. Check the logs,
383247
find the problem, and fix it.
384248
```
385249

386-
### What Vibecode Agent Can Do
387-
388-
With this agent and [MCP integration](https://github.com/Coolver/home-assistant-mcp), AI IDE can:
389-
390-
**Analyze YOUR configuration** - detects your actual devices and entities
391-
**Create complex systems autonomously** - 10+ interconnected automations
392-
**Tailored to your setup** - uses your specific entity IDs and device capabilities
393-
**Automatic backups** - every change is Git-versioned with meaningful commit messages
394-
**View change history** - ask AI to show recent commits and what changed
395-
**Easy rollback** - ask AI to rollback to any previous version by description or date
396-
**Intelligent debugging** - reads logs, finds issues, fixes them
397-
**Error recovery** - can rollback if something goes wrong
398-
**End-to-end deployment** - from analysis to production
399250

400251
**Stop writing YAML manually! Just describe what you want.** 🚀
401252

@@ -482,97 +333,9 @@ For detailed contribution guidelines, see **[CONTRIBUTING.md](CONTRIBUTING.md)**
482333

483334
---
484335

485-
## 🎯 Use Cases
486-
487-
### For Cursor AI, VS Code + Co-Pilot etc
488-
489-
This agent enables Cursor AI to:
490-
491-
1. **Autonomously install systems** - AI reads current config, creates all components, tests
492-
2. **Debug issues** - AI reads logs, configs, entity states, fixes problems
493-
3. **Evolve configurations** - AI improves automations based on usage patterns
494-
4. **Safe experimentation** - Git versioning allows instant rollback
495-
5. **Complete automation** - No manual steps required!
496-
497-
### Example Workflow
498-
499-
```
500-
User: "Install smart climate control system"
501-
502-
AI via Agent:
503-
1. Reads current TRV entities
504-
2. Creates backup
505-
3. Creates 7 input helpers
506-
4. Adds 12 template sensors to configuration.yaml
507-
5. Creates 5 scripts
508-
6. Creates 10 automations
509-
7. Reloads all components
510-
8. Validates installation
511-
9. Shows dashboard YAML for user to add
512-
513-
User: "Show me the last 10 changes to my configuration"
514-
515-
AI via Agent:
516-
1. Calls `ha_git_history` to get commit history
517-
2. Displays commits with meaningful messages:
518-
- "Add automation: Control lights when motion detected"
519-
- "Update theme: Change primary color to blue"
520-
- "Add helper: Enable/disable climate system"
521-
3. Shows timestamps and commit hashes
522-
4. Helps identify which changes to review
523-
524-
User: "Something broke! Rollback to the version from yesterday"
525-
526-
AI via Agent:
527-
1. Gets recent commit history
528-
2. Finds commits from yesterday
529-
3. Shows options with descriptions
530-
4. Rolls back to selected version
531-
5. Verifies rollback was successful
532-
533-
User: "Rollback to when I added the motion sensor automation"
534-
535-
AI via Agent:
536-
1. Searches commit history for "motion sensor automation"
537-
2. Finds matching commit
538-
3. Shows commit details
539-
4. Rolls back to that specific version
540-
3. Restarts HA
541-
4. Verifies restoration
542-
```
543-
---
544-
545-
## ⚠️ Important Notes
546-
547-
### Git Versioning
548-
549-
- Creates `.git` folder in `/config` if not exists
550-
- Auto-commits on every change (if enabled)
551-
- **Meaningful commit messages**: AI-generated descriptive messages explaining what and why changed
552-
- Examples: "Add automation: Control lights when motion detected", "Update theme: Change primary color to blue"
553-
- Messages are generated based on operation context and user-provided descriptions
554-
- Stores up to 30 commits (configurable via `max_backups`)
555-
- Automatic cleanup: When reaching max commits, keeps last 20 commits (maintains buffer)
556-
- Commit messages include operation details and context
557-
558-
### File Operations
559-
560-
- All paths are relative to `/config`
561-
- Cannot access files outside config directory
562-
- Automatic backup before write/delete
563-
- YAML validation on parse
564-
565-
### Service Calls
566-
567-
- Full access to Home Assistant API
568-
- Can call any service (lights, climate, system, etc.)
569-
- Requires proper entity IDs
570-
571-
---
572-
573336
## 🐛 Troubleshooting
574337

575-
### "spawn npx ENOENT" error (Cursor / VS Code / Other IDE Console)
338+
### "spawn npx ENOENT" error (Claude Code / Cursor / VS Code / Other IDE Console)
576339

577340
This error means Node.js is not installed or not found in your system PATH.
578341

0 commit comments

Comments
 (0)