Home-Assistant/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

The Home Assistant configuration directory (/config on the live HAOS host, mirrored to this git repo). It is configuration, not application code — there is no build or test suite. "Running" a change means HA loads it; validation is by config-check and reload, not unit tests. The repo is also mirrored to a self-hosted Gitea at code.cubecraftlabs.com (origin is https://code.cubecraftlabs.com/overseer/Home-Assistant.git).

Edits here only take effect after they reach the live host and HA reloads the affected domain. There is no compile step; a malformed YAML file breaks the domain it belongs to (or all of HA if it's configuration.yaml).

Layout & how config is assembled

configuration.yaml is the root that wires everything together via !include directives. Understand these to know where a given entity lives:

• packages/ → !include_dir_named — each file is a self-contained feature that can declare automations, sensors, MQTT entities, helpers, etc. all at once. This is where the major subsystems live (cat medication, chore tracker, litter box monitor, voice satellite alarms, integration health).
• automations/ → !include_dir_merge_list — numbered files (01_–07_) group automations by theme (home/lighting, alerts, presence/security, kids, printers, dashboards, climate). print_log_automations/ is a subfolder for the 3D-printer→Notion logging automations. All are merged into one flat list, so id: and alias: must be globally unique across every file.
• helpers/ → one file per helper domain (input_boolean, input_number, input_select, input_datetime, counter, timer, input_text, rest_command, shell_command). Add a new helper to the matching domain file.
• dashboards/ → dashboards.yaml registers each Lovelace dashboard; view definitions live in dashboards/views/.
• themes/, blueprints/, scenes.yaml, scripts.yaml — standard HA locations.
• esphome/ → firmware for ~150 ESP devices (see below).
• scripts/ → host-side shell/Python services that run alongside HA (not HA script: entities).

Secrets are referenced as !secret <key>; secrets.yaml, known_devices.yaml, ip_bans.yaml and the HA runtime DB/storage are gitignored. The .gitignore uses an ignore-all-then-whitelist pattern — new file types or folders won't be tracked unless explicitly whitelisted there.

ESPHome devices (esphome/)

Two structural patterns coexist:

1. Single-file devices — e.g. cat-medication-tracker.yaml, airqualitysensor-*.yaml.
2. Package-based devices — a thin top-level entry file sets substitutions: (per-board pins) and pulls in shared logic via packages: !include <dir>/<base>.yaml. See jarvis-satellite/, respeaker-satellite/, ha-remote/, family-room-remote/. To change shared behavior edit the package dir; to change one physical device edit its top-level substitutions.

Custom C++ components/headers live alongside the YAML (esphome/components/, MAX17048_component.h, spi_helper.h) and are referenced via esphome: includes:. This framework is arduino-type but ESP-IDF-hybrid — use ESP-IDF headers (driver/spi_master.h, driver/gpio.h), not Arduino SPI.h, which is not on the include path. Display MADCTL/orientation fixes that must run after ESPHome's model init are done in an on_boot lambda at priority -100 (not init_sequence:, which gets overwritten). The cat-medication-tracker is the worked reference for this.

Generated ESPHome configs — DO NOT hand-edit

esphome/chore-tracker/generate.py is the source of truth for the chore tracker. It reads chore-tracker/chores_config.yaml and emits three files marked AUTO-GENERATED:

• esphome/chore-tracker-esphome.yaml (firmware)
• packages/chore_tracker_ha.yaml (HA entities/automations)
• esphome/chore-tracker/chore-tracker-dashboard.yaml (Lovelace)

To change chores or kids, edit chores_config.yaml then regenerate:

cd esphome/chore-tracker && python3 generate.py

Any file whose header says AUTO-GENERATED — edit chores_config.yaml must not be edited directly; changes will be overwritten.

Host-side services (scripts/)

These run on the HA host as background processes, independent of HA itself:

• litter_box_analyzer.py — OpenCV/MQTT computer-vision service. Subscribes to base64 JPEG frames an ESP32-S3 camera publishes over MQTT, detects cat presence / box-stuck / needs-scooping, and publishes results back to litter_box/status/* topics. packages/litter_box_monitor.yaml consumes those topics as HA MQTT sensors. Requires opencv-python numpy paho-mqtt. Manage it with scripts/litter_box_analyzer.sh {start|stop|restart|status} (configurable via MQTT_BROKER, MOTION_THRESHOLD, etc. env vars).
• git_autocommit.sh — invoked by the git_autocommit shell_command helper; stages /config, commits with a timestamp, and pushes main. This is how HA-side edits get committed back to git.

Print Log → Notion integration

3D-printer activity is logged to a Notion database in real time. helpers/rest_command.yaml defines notion_create_print (POST, returns page id) and notion_update_print (PATCH by page id); automations in automations/print_log_automations/ (one start+finish pair per printer) call them. Key gotchas captured in print_log_context.md:

• rest_command responses are already parsed dicts — use {{ notion_response.content.id }}, never | from_json.
• The Notion bearer token is the full "Bearer ntn_..." string stored as !secret notion_token_bearer.
• Bambu vs. Elegoo printers expose different sensor sets (Elegoo only has file_name + print_status).

Conventions

• Unique ids: automations are merged into one list — never reuse an id: or alias:.
• Network: IoT VLAN is 192.168.69.x / 10.60.1.x, main LAN 192.168.1.x; ESP devices use wifi_iot_ssid. The http: block trusts proxy 10.60.1.1.
• Don't commit secrets or runtime state — rely on the existing .gitignore whitelist; if you add a new tracked file type, whitelist it explicitly.