homeassistant-assistant

🏠 Home Assistant Assistant

Your Home Assistant setup, understood by AI — grounded in your live entities and the official docs, not guesses.

A GitHub Copilot / Claude Code / GitHub Copilot CLI workspace for building automations, scripts, and configurations on your existing Home Assistant installation. It is not for Home Assistant core development.

Before answering, the agent checks what you actually have (via MCP) and how Home Assistant says to do it (via the official docs). That combination is what keeps it from hallucinating entity IDs or deprecated YAML syntax.

📚 Contents

• ✨ Features
• 🧰 Prerequisites
• 📦 Installation
• 🗂️ Fetching your Home Assistant configs
• 💡 Usage examples
• 🗺️ Project structure
• 📖 Resources
• 🧯 Troubleshooting

✨ Features

• 🔌 Live entity context — pulls real devices, entities, and areas via GetLiveContext before suggesting anything.
• 📚 Docs-grounded answers — fetches the official Home Assistant docs and cites the exact section used.
• 🩺 Troubleshooting playbook — a guided flow through config checks, traces, and logs when something misbehaves.
• 🔧 ESPHome support — device YAML authoring backed by the esphome.io sitemap.
• 📰 Release notes analyzer — personalized summaries of new HA releases based on your actual setup.
• 🧪 Multi-model benchmarking — compares release-note summaries across models against your live setup.
• 🔐 Read-only SSH guard — a hook that blocks destructive SSH commands against your Home Assistant host.
• 🧩 Cross-tool plugin — the same skills, agents, and hook install into VS Code, Claude Code, and GitHub Copilot CLI.

🧰 Prerequisites

• A Home Assistant instance with the Model Context Protocol Server integration enabled.
• A long-lived access token.
• SSH access to Home Assistant with a host alias homeassistant in ~/.ssh/config (passwordless), used only to fetch automations, scenes, scripts, and logs.
• One of: VS Code with GitHub Copilot, Claude Code, or GitHub Copilot CLI.

🔗 Enabling the Home Assistant MCP server

1. Go to Settings → Devices & services → Add Integration.
2. Search for Model Context Protocol Server and follow the setup flow.
3. Go to Profile → Security → Long-lived access tokens and create a token.

The integration exposes an endpoint at /api/mcp over the Streamable HTTP transport — that's the URL and transport every config in this repo uses.

📦 Installation

Pick the client you use. All three read the same skills, agents, and hook — only the setup command differs.

🖥️ VS Code

git clone https://github.com/calexandre/homeassistant-assistant.git
code homeassistant-assistant

VS Code prompts for:

• Host — your Home Assistant URL without https:// (e.g. homeassistant.local:8123).
• Bearer token — the long-lived access token you created above.

The MCP configuration lives in .vscode/mcp.json; skills, agents, and the SSH guard hook load automatically from .github/.

🤖 Claude Code

No checkout needed — add the marketplace and install the plugin straight from GitHub:

export HA_HOST="homeassistant.local:8123"
export HA_BEARER_TOKEN="your-long-lived-token"
claude plugin marketplace add calexandre/homeassistant-assistant
claude plugin install homeassistant-assistant@homeassistant
claude

🐙 GitHub Copilot CLI

No checkout needed — add the marketplace and install the plugin straight from GitHub:

export HA_HOST="homeassistant.local:8123"
export HA_BEARER_TOKEN="your-long-lived-token"
copilot plugin marketplace add calexandre/homeassistant-assistant
copilot plugin install homeassistant-assistant@homeassistant
copilot

🗂️ Fetching your Home Assistant configs

Automations, scenes, scripts, configuration.yaml, and logs are not exposed by the MCP server. Fetch them over SSH instead:

.github/skills/ha-config-fetch/fetch-ha-data.sh

Files land in ha-data/ (gitignored). The script assumes the standard HAOS config path (/config); override it if needed:

.github/skills/ha-config-fetch/fetch-ha-data.sh /custom/config/path

💡 Usage examples

Open the chat, pick the Home Assistant Agent 🏠, and ask away.

🩺 Debugging

> My motion sensor automation isn't triggering — help me debug it.

> Why does this template return unknown? {{ states('sensor.temperature') | float }}