ha-nova

What is HA NOVA?

HA NOVA gives your AI a way to actually control Home Assistant — without randomly breaking things.

Let an AI agent loose on your smart home and it'll happily create, change, or delete stuff without thinking twice. HA NOVA stops that. Every risky change follows a clear path: research first, preview what's about to happen, apply only after confirmation, then verify it actually worked.

The intelligence lives in plain markdown files called skills. They teach the AI how Home Assistant works, what to watch out for, and how to do things right. No code — just text files. Adding a new capability means writing a markdown file.

The relay is a small app running on your HA server. It keeps your token where it belongs — on the server, not on your laptop — and handles everything that needs direct host access. It stays small on purpose. The relay is the hands. The skills are the brain.

A setup wizard handles installation. Pick your AI client, follow the prompts, done.

Works with Claude Code, Claude Desktop (Code tab), Codex CLI, OpenCode, and Gemini CLI.

Early access. The core works well, but expect rough edges. Back up your configs before letting AI touch anything. Hit a problem? Open an issue.

See it in action

"When I get home, set the living room lights to a warm welcome ambiance" — one sentence in, a fully reviewed automation out, including suggestions you might not have thought of.

🚀 Quick Start

You need: Home Assistant OS or Supervised. HA NOVA itself does not need Node.js for normal use, but some AI clients do.

Stable install (recommended)

1. Open the latest GitHub release
2. Copy the one-liner for your OS
3. Run it unchanged

This makes sure you install exactly the version shown on that release page.

macOS / Linux

macOS has been tested on a real machine. Linux uses the same installer and passes automated checks, but has not had the same real-machine testing yet.

Windows PowerShell

Windows currently ships an x64 build. On Windows ARM64, use x64 emulation.

Claude currently has the deepest Windows validation. Gemini CLI has basic Windows validation for this release. Codex and OpenCode on Windows are still early.

The wizard guides you through the Home Assistant connection and client setup. Once done, open your client and try: "Show me all my automations."

HA NOVA installs the local HA NOVA tools. Install the AI client itself separately if you haven't already. Windows uses a single supported install path: install.ps1. Native Windows client prerequisites still apply: Claude Code needs Git for Windows / Git Bash, and Gemini CLI needs Node.js. See .claude/INSTALL.md and .gemini/INSTALL.md before running the HA NOVA installer. On a supported local PowerShell or Windows Terminal session, that same one-liner starts the guided setup flow directly when at least one supported client is already installed and runnable; no second terminal command is needed. If no supported client is ready yet, HA NOVA still installs locally and tells you which client prerequisite is still missing. HA NOVA installs itself on your computer; the Home Assistant connection steps stay guided in the browser.

Do not download the release ha-nova-installer-bundle-*.tar.gz / .zip assets and try to launch them manually. Those archives are files the installer uses behind the scenes. Use install.sh, install.ps1, or ha-nova update.

Old pre-Go install?

• macOS / Linux: curl -fsSL https://raw.githubusercontent.com/markusleben/ha-nova/main/scripts/legacy-uninstall.sh | bash
• Windows: irm https://raw.githubusercontent.com/markusleben/ha-nova/main/scripts/legacy-uninstall.ps1 | iex

Already installed? ha-nova check-update or ha-nova update | Need to reconfigure? ha-nova setup | Something broken? ha-nova doctor | Need a full local wipe? ha-nova uninstall --purge

Default ha-nova uninstall is now a standard remove. It removes the installed HA NOVA files, skills, and cache, but keeps your saved HA NOVA connection settings and sign-in for easier reinstall/repair. Use --purge for the old full-cleanup behavior.