Managing Home Assistant with Claude Code

I’ve written about how I use Claude Code and about Home Assistant separately. This post is about what happens when you combine them. Home Assistant is powerful, but managing it can be tedious. Dashboard layouts are deeply nested JSON. Automations require getting YAML syntax exactly right. Renaming a device means editing an internal registry. None of it is too hard — it’s just fiddly and time-consuming. Claude Code turns these tasks into conversations.

How It Connects#

The Home Assistant Green runs an SSH add-on with key-based authentication. The SSH key lives in 1Password ↗, and macOS is configured to use the 1Password SSH agent globally. That means Claude Code can run ssh homeassistant "cat /config/automations.yaml" and it just works — 1Password handles the key at connection time, confirming with touchID, no passwords or key files sitting on disk.

The local project directory has a CLAUDE.md that tells Claude Code everything about the HA environment — the SSH hostname, key file paths on the HA instance, dashboard file-to-name mappings, entity IDs, coordinator details, and general notes about the setup. There’s also an inventory file listing every integration, device, area, automation, and custom component installed. This means Claude Code starts every session already knowing the full environment without having to discover anything.

What It Does#

Automations and Scripts#

Claude Code SSHs into Home Assistant and reads configuration files directly. For automations, it can read automations.yaml, explain what each one does, add new automations with correct YAML syntax, or modify triggers, conditions, and actions on existing ones.

The real value shows up with complex tasks. When I wanted to set up appliance monitoring for my washing machine using a community blueprint, Claude Code read the blueprint YAML to understand all of its input options, found the correct entity IDs for the power-monitoring plug, identified my mobile device ID for notifications, and wrote a complete automation entry with power thresholds, debounce settings, notification messages, and status tracking. Then it created the input helper for the dashboard and restarted HA to apply everything. That whole process would have taken me a while to do manually — figuring out the blueprint’s input schema alone is tedious.

Dashboard Editing#

Home Assistant dashboards are stored as JSON in /config/.storage/. Claude Code downloads the JSON over SSH, parses it, makes changes, and uploads the result. This is where it saves the most time. Adding a conditional badge that only appears when the washing machine is running, setting up dynamic weather icons that change based on conditions, or configuring Mushroom cards with the right entity IDs and display properties — all of this involves deeply nested JSON that’s painful to hand-edit.

The workflow is: read the file over SSH, pipe through python3 locally for JSON manipulation (HA OS doesn’t have python3 installed), then write the result back. Claude Code handles this entire pipeline.

Device Management#

Some changes require editing Home Assistant’s internal .storage files directly. When I repurposed a smart plug from a Christmas tree to the washing machine, Claude Code found all entities associated with the device in the entity registry, stopped HA core (so the registry wouldn’t get overwritten on shutdown), renamed all the entity IDs and unique IDs, uploaded the modified registry, and started HA core back up. Doing that manually means finding the right JSON file, understanding the data structure, making changes without breaking anything, and getting the stop/edit/start sequence right.

Troubleshooting#

This might be where Claude Code adds the most value. Home Assistant problems can be genuinely hard to diagnose. An automation that stopped firing, a device that shows unavailable intermittently, an entity that’s returning stale data — these issues often involve tracing through multiple files, checking logs, cross-referencing entity IDs, and understanding how different parts of the system interact. That’s exactly the kind of tedious, detail-heavy investigation that Claude Code is good at.

It can pull the HA logs over SSH, read the relevant automation or integration config, check the entity registry for mismatches, and piece together what’s going wrong — all in one conversation. Problems that would take me 20 minutes of jumping between files and docs often get resolved in a couple of exchanges.

HA Core Lifecycle#

Claude Code can restart or reload Home Assistant through the Supervisor API over SSH. The Supervisor token is an environment variable injected into the SSH add-on container at runtime — it’s never stored locally or included in any config files. Claude Code references it by variable name in SSH commands, so the actual token value is resolved on the HA side.

A Word of Caution#

I want to be clear: giving an AI tool SSH access to a system that controls your home is something you should think carefully about before doing. Home Assistant manages locks, cameras, alarms, and other things with real physical consequences. If you’re going to experiment with this, do it deliberately and with guardrails.

Don’t give it more access than it needs. Scope SSH access to the HA config container, not a general-purpose shell. Don’t hand it admin credentials to your router, your NAS, or anything else on the network.

Never store credentials in the project or with Claude Code. No API tokens in CLAUDE.md. No passwords in config files. No SSH keys on disk. Use an agent like 1Password’s SSH agent so the key material is never exposed. If Claude Code needs to reference a token, it should be by environment variable name, resolved on the remote side — never as a literal value in a command.

Be aware of prompt injection. If Claude Code reads content from external sources — log files, API responses, community forum posts, or anything user-generated — that content could theoretically contain instructions that try to manipulate its behavior. Review what it’s about to execute before approving, especially after it’s ingested content from sources you don’t fully control.

Keep the approval prompts on. It’s tempting to auto-approve everything for speed, but for SSH commands against a live system, you should be reviewing each one. The few seconds it takes to read a command before hitting enter is the difference between a safe workflow and a mistake that locks you out of your house.

With all that said, here’s how I keep it safe in practice.

How I Keep It Safe#

Every command requires approval. Claude Code doesn’t silently execute anything. Every SSH call, file write, or shell command is presented in the terminal before it runs. You see the full command and approve or deny each one. You can also configure permission levels to auto-approve reads while always prompting for writes.

No credentials on disk. The SSH key lives exclusively in 1Password. The 1Password SSH agent brokers authentication at connection time — there’s no key file for anything to leak. If the vault is locked, SSH fails. Claude Code never sees the private key material.

No stored API tokens. The Supervisor token is a runtime environment variable in the SSH container. It’s never written to a file, never included in CLAUDE.md, and never stored locally.

Read-before-write. Claude Code reads existing files before modifying them. It doesn’t generate a new automations.yaml from scratch — it reads the current one, understands what’s there, and appends or modifies only what’s needed. Existing automations, formatting, and comments are preserved.

HA validates on restart. If Claude Code writes malformed YAML, Home Assistant will log the error and either skip the invalid entry or refuse to start with a clear message. It won’t silently apply broken configuration. And HA’s built-in backup system captures the entire /config/ directory automatically, so restoring from a mistake is straightforward.

Scoped access. The SSH connection lands in the HA OS container, which is sandboxed. It has access to /config/ and the Supervisor API, but it’s not a general-purpose Linux box. There’s no package manager, no way to install software, and no access to the host OS.

Lessons Learned#

HA OS is minimal. There’s no python3, no jq, no package manager on the HA instance. Any JSON or YAML processing has to happen locally by piping SSH output through local tools.

Entity registry timing matters. HA writes its internal registries to disk on shutdown. If you edit a registry file and then restart HA, the shutdown phase overwrites your changes with the in-memory state. The fix is to stop HA first (so it writes current state), edit the file, then start HA (so it reads the modified version).

Blueprint inputs aren’t obvious. Blueprints can have dozens of inputs with specific expected values — like a literal string "enable_start_notify_options" rather than true. Claude Code reads the full blueprint YAML to discover correct input names, types, and selector configurations rather than guessing.

The Pattern#

The common thread is that Claude Code handles the mechanical parts — SSH connections, file parsing, YAML syntax, JSON manipulation, API calls, restart sequences — while I describe what I want in plain language. The CLAUDE.md gives it the environment context, the inventory file gives it the device knowledge, and the approval system keeps me in control of what actually executes. It’s the same pattern I described in the Claude Code post, just applied to home automation instead of software development.