🏠 Home Assistant Assistant

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

Skills and a safety hook for Claude Code, GitHub Copilot CLI, and VS Code with GitHub Copilot that help you build automations, scripts, scenes, and ESPHome configs for 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 keeps it from inventing entity IDs or suggesting deprecated YAML.

📚 Contents

• ✨ Features
• 🧭 How it works
• 🧰 Prerequisites
• 🔗 Set up the Home Assistant MCP server
• 📦 Installation
• ✅ Check that it works
• 📂 Optional: SSH snapshots
• 💡 Usage examples
• 🔒 Safety and privacy
• 🧱 Project structure
• 🧯 Troubleshooting
• 🤝 Contributing
• 📄 License

✨ Features

• 🔌 Live entity context — pulls your real devices, entities, and areas via GetLiveContext before suggesting anything.
• 📚 Docs-grounded answers — looks up the official Home Assistant and ESPHome docs and cites the exact section used.
• 🩺 Troubleshooting playbook — a guided flow through config checks, logs, traces, and Developer Tools when something misbehaves.
• 🔧 ESPHome support — device YAML authoring backed by an esphome.io sitemap.
• 📂 Config snapshots — optional read-only SSH snapshots of automations, scripts, scenes, ESPHome YAMLs, Zigbee2MQTT data, and logs.
• 🔐 Read-only SSH guard — a hook that blocks destructive SSH commands against your Home Assistant host, whether they run in Bash or PowerShell.
• 🧩 Cross-tool plugin — the same skills and hook work in Claude Code, GitHub Copilot CLI, and VS Code.

🧭 How it works

flowchart LR
  user([You]) --> agent["Your AI agent + skills<br/>Claude Code · Copilot CLI · VS Code"]
  agent -->|"MCP · GetLiveContext"| ha[("Home Assistant")]
  agent -->|"looks up"| docs["Official docs<br/>home-assistant.io · esphome.io"]
  agent -->|"reads"| snap["ha-data/ snapshots"]
  ha -->|"SSH, read-only · optional"| snap
  guard{{"SSH read-only guard"}} -.->|"checks every shell command"| agent

Every request starts at the homeassistant skill, which calls GetLiveContext and then routes to the skill that fits:

🧰 Prerequisites

Claude Code runs the hook as python3 on every platform, including Windows. The Copilot clients run it as python3 on Linux/macOS and as python on Windows.

🔗 Set up the Home Assistant MCP server

1. In Home Assistant, go to Settings → Devices & services → Add Integration, search for Model Context Protocol Server, and finish the setup flow.
2. Go to Settings → Voice assistants → Expose and expose the entities you want the agent to see. The default Device control tools only see exposed entities, so anything you leave out is invisible to the agent.
3. Note your MCP URL: your Home Assistant URL followed by /api/mcp, for example https://example.ui.nabu.casa/api/mcp.
4. For VS Code and Copilot CLI, create a token under Profile → Security → Long-lived access tokens. Claude Code can sign in through your browser instead.

Use an HTTPS URL when you can (Home Assistant Cloud, a reverse proxy, or Home Assistant's own TLS): the Home Assistant docs note that Claude Code only connects to MCP servers over HTTPS. VS Code also accepts a plain http://homeassistant.local:8123 URL on your local network.

The integration's options control which tools it exposes and whether it requires an administrator account (on by default). See the integration docs for the details.

📦 Installation

Pick your client. All three load the same skills and hook.

🤖 Claude Code

claude plugin marketplace add calexandre/homeassistant-assistant
claude plugin install homeassistant-assistant@homeassistant
claude mcp add --scope user --transport http homeassistant https://YOUR-HOME-ASSISTANT/api/mcp
claude mcp login homeassistant

claude mcp login opens your browser to sign in to Home Assistant, so there is no token to copy. To use a long-lived token instead, skip the login and add the server with a header, as shown for Copilot CLI below (claude mcp add takes the same --header flag).

🐙 GitHub Copilot CLI

copilot plugin marketplace add calexandre/homeassistant-assistant
copilot plugin install homeassistant-assistant@homeassistant
read -rs HA_TOKEN
copilot mcp add --transport http homeassistant https://YOUR-HOME-ASSISTANT/api/mcp --header "Authorization: Bearer $HA_TOKEN"

read -rs waits silently: paste the long-lived token and press Enter, which keeps it out of your shell history. In PowerShell, run $HA_TOKEN = Read-Host -MaskInput instead; the copilot mcp add line works as is. Copilot CLI saves the server in ~/.copilot/mcp-config.json.

🖥️ VS Code

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

Skills and the SSH guard hook load automatically from .github/. VS Code keeps MCP servers in the Copilot Global configuration, ~/.copilot/mcp-config.json, the same file Copilot CLI writes, so a server you added with copilot mcp add above is already there.

Otherwise, run MCP: Add Server, choose HTTP, enter https://YOUR-HOME-ASSISTANT/api/mcp, use the ID homeassistant, and save it to Global → Copilot Global. Then add your long-lived token to that server's entry in ~/.copilot/mcp-config.json:

"headers": {
  "Authorization": "Bearer YOUR_LONG_LIVED_TOKEN"
}

✅ Check that it works

Ask a question only your house can answer:

> Which lights are on right now?

The answer should name your real entities. If the agent says it cannot reach Home Assistant, list your MCP servers with claude mcp list, copilot mcp list, or the MCP: List Servers command in VS Code, then see Troubleshooting.

📂 Optional: SSH snapshots

The MCP server exposes live entity state, but not your automation, script, or scene definitions, config files, or logs. With SSH access, the agent pulls read-only snapshots of those into ha-data/ in your working directory (gitignored in this repo).

[!IMPORTANT]
SSH access requires a host alias named exactly homeassistant in ~/.ssh/config. The fetch script connects to that name, and the read-only guard only protects commands that target it: under any other alias, snapshots fail and the guard can't block writes to your host.

1. Install an SSH add-on in Home Assistant and add your public key to it. The official Terminal & SSH add-on covers config files and ESPHome YAMLs; the community Advanced SSH & Web Terminal add-on with protection mode off covers everything.

2. Add the homeassistant host alias to ~/.ssh/config, with HostName, User, and Port set to your Home Assistant host and what your add-on uses:

   Host homeassistant
     HostName homeassistant.local
     User root
     Port 22
     IdentityFile ~/.ssh/id_ed25519
   

3. Check that it logs in without a password prompt:

   ssh homeassistant ls /config
   

4. Ask the agent to "refresh my Home Assistant data", or run the script yourself from a clone of this repo:

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

The script reads /config by default. If your add-on mounts the config elsewhere, pass the path: .github/skills/ha-config-fetch/fetch-ha-data.sh /homeassistant.

💡 Usage examples

Just ask, in any client: the homeassistant skill picks up any Home Assistant request. In VS Code, use Chat in Agent mode.

🤖 Creating automations

> Create an automation that turns on the living room lights at sunset,
  but only if someone is home.

> Turn my kitchen ceiling switch into a scene that also dims the hall lights.

Answers come as ready-to-paste YAML, a short "How This Works" with links to the docs used, and customization ideas.

🩺 Debugging

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

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

The troubleshooting skill walks through config checks, automation traces, and logs before proposing a fix.

📊 Checking your home

> Which battery sensors are below 20%?

> Are any of my automations using deprecated syntax?

🔧 ESPHome devices

> Add a BME280 sensor to the hall corridor wall switch over I2C.

🔒 Safety and privacy

• Read-only SSH guard. A PreToolUse hook inspects every Bash and PowerShell command. Commands that reach the homeassistant host must match a read-only allowlist; interactive SSH, uploads (scp, sftp, rsync), and everything else are denied. It guards against mistakes; it is not a sandbox.
• Device control stays with you. The skills only need GetLiveContext to read your home, and your client asks before each MCP tool call. For a hard guarantee, turn on the integration's Read-only option.
• What leaves your machine. Entity names and states from GetLiveContext, and any snapshot the agent reads (automations, logs, Zigbee2MQTT state), are sent to your AI provider as part of the conversation. secrets.yaml is never fetched.
• Tokens. Claude Code's browser sign-in avoids handling a token at all. Otherwise use read -rs as shown above so the token stays out of your shell history. Copilot CLI and VS Code store the token in ~/.copilot/mcp-config.json, so keep that file private and out of any dotfiles repo.

🧱 Project structure

.claude-plugin/
├── plugin.json            # Plugin manifest (Claude Code + Copilot CLI)
├── marketplace.json       # Marketplace entry used by `plugin marketplace add`
└── icon.png               # Plugin icon
hooks/hooks.json           # SSH read-only guard, Claude Code / Copilot CLI hook format
.github/
├── skills/                # Domain skills (SKILL.md), auto-discovered by every client
├── hooks/                 # SSH read-only guard script, its tests, VS Code hook format
└── instructions/          # Markdown style rules for VS Code
AGENTS.md                  # Instructions for coding agents working on this repo
ha-data/                   # Fetched HA snapshots and logs (gitignored)
.temp/                     # Scratch output (gitignored)

🧯 Troubleshooting

The agent can't reach Home Assistant:

1. Check the server's status with claude mcp list, copilot mcp list, or MCP: List Servers in VS Code.
2. Check that the URL ends in /api/mcp, uses the right scheme (https:// for Claude Code), and opens from this machine.
3. On 401 Unauthorized, the token is wrong or revoked: create a new one, or run claude mcp login homeassistant again.
4. The integration requires an administrator account by default, so a token from a non-admin user fails. Use an admin token or change that option in the integration.

The agent says a device doesn't exist: expose it under Settings → Voice assistants → Expose. The Device control tools only see exposed entities.

The plugin doesn't load in Claude Code or Copilot CLI:

claude plugin marketplace update homeassistant
claude plugin list
copilot plugin marketplace update homeassistant
copilot plugin list

From a local clone, validate the manifests with claude plugin validate ..

SSH snapshots fail: run ssh homeassistant ls /config first. If that works but Zigbee2MQTT data or logs are skipped, check the snapshot table for the access each one needs.

Shell commands fail with an SSH guard hook startup error:

Confirm Python is available: run python3 --version for Claude Code on any platform and for Copilot on Linux/macOS, or python --version for Copilot on Windows. On Windows, a python3 or python command that only opens the Microsoft Store is an app execution alias, not an interpreter; install Python or turn the alias off in Settings → Apps → Advanced app settings → App execution aliases. The hook uses separate PowerShell and Bash launchers and inspects both the Bash and PowerShell tools; restart the client after changing hook configuration so it reloads. All Git subcommands, including commit and push, are allowed by this hook; the read-only restrictions apply only to direct SSH/file-transfer commands targeting homeassistant.

🤝 Contributing

Questions and ideas are welcome in Discussions; bugs go to Issues. See CONTRIBUTING.md for how to test changes, and SECURITY.md to report a vulnerability privately.

📄 License

MIT

📖 Resources

• Home Assistant docs
• Model Context Protocol Server integration
• ESPHome docs
• Claude Code plugins
• GitHub Copilot
• Model Context Protocol