home-assistant-assistant: Instructions file for Claude Code

AGENTS.md

Shared guidance for Claude Code and Codex when working in this repository.

Project Overview

This is a Claude Code and Codex plugin for Home Assistant. It allows users to manage Home Assistant configurations through natural language: creating automations, scripts, scenes, and dashboards by describing what they want instead of manually editing YAML.

Type: Claude Code and Codex plugin (markdown-based, no build system or compiled code)

Safety Invariants

All generated YAML and commands enforce eight safety invariants (canonical wording in references/safety-invariants.md):

1. No unsupported attributes - Always check supported_features/supported_color_modes before suggesting device attributes
2. No semantic substitution - Never replace "after no motion" (inactivity) with raw timers
3. AST editing only - No brittle string replacement; use Edit tool with precise old/new strings
4. No secrets printed - Never echo tokens; show "TOKEN is set" not the value
5. Never deploy unless explicitly requested - All side-effectful skills require explicit user request and confirmation
6. Evidence tables - All validation outputs show "what ran vs skipped"
7. Minimal edits only - Make only the specific changes requested; do not reorganize adjacent content
8. Verify after config edits - Offer deploy/reload after YAML changes; validate entity IDs exist before use

Plugin Architecture

The plugin has two agent-facing surfaces that share one canonical workflow source:

• Claude Code reads .claude-plugin/, skills/, agents/, and hooks/.
• Codex installs plugins/home-assistant-assistant/ from .agents/plugins/marketplace.json; inside that package, Codex reads .codex-plugin/, skills/, codex/, and packaged support files.
• Canonical Home Assistant behavior stays in root skills/ and references/; Codex wrappers adapt invocation/tool semantics without forking domain logic and read packaged canonical copies from canonical-skills/.

.claude-plugin/
  plugin.json               # Claude plugin manifest - metadata, component discovery
.agents/plugins/
  marketplace.json          # Codex marketplace source; points at ./plugins/home-assistant-assistant
plugins/home-assistant-assistant/
  .codex-plugin/plugin.json # Codex plugin manifest for the installable package
  skills/                   # Codex-visible wrapper skills; the only SKILL.md tree in the package
  canonical-skills/         # Packaged shared workflow docs as README.md files, not SKILL.md
  codex/                    # Codex hooks and adapter reference
  helpers/, references/, templates/
skills/
  ha-automations/           # Automation creation + domain knowledge (user-invocable)
  ha-scripts/               # Script creation + domain knowledge (user-invocable)
  ha-scenes/                # Scene creation + domain knowledge (user-invocable)
  ha-config/                # Config organization knowledge (user-invocable)
  ha-jinja/                 # Jinja templating knowledge (user-invocable)
  ha-lovelace/              # Dashboard design knowledge (user-invocable)
  ha-naming/                # Naming conventions + audit + plan (user-invocable)
  ha-apply-naming/          # Naming execution (user-invocable, NO model invocation)
  ha-devices/               # Device knowledge + new device workflow (user-invocable)
  ha-troubleshooting/       # Debugging knowledge (user-invocable)
  ha-onboard/               # Setup wizard + connection + settings (user-invocable)
  ha-deploy/                # Deploy + rollback (user-invocable, in-skill confirmation gates)
  ha-validate/              # Validation workflow + procedures (user-invocable, agent-preloadable)
  ha-analyze/               # Setup analysis + recommendations (user-invocable)
  ha-resolver/              # Entity resolution (NOT user-invocable, agent-preloaded)
codex-skills/
  ha-*/                     # Source Codex wrapper skills copied into the installable package skills/ tree
codex/
  hooks.json                # Codex hook mapping
  session_check.py          # Codex SessionStart check (no Bash dependency)
  env_guard.py              # Codex PreToolUse guard, including PowerShell env dumps
  references/skill-adapter.md
agents/
  *.md                      # 6 subagents: config-debugger, ha-config-validator,
                            # device-advisor, naming-analyzer, ha-entity-resolver,
                            # ha-log-analyzer
helpers/
  area-search.py            # Area-based entity search (registry cross-referencing)
  entity-registry.py        # Entity registry operations
  ha-overview.py            # HA setup overview generation
  trace-fetch.py            # Automation trace fetching
  lovelace-dashboard.py     # Lovelace dashboard fetch/save/verify/find-entities
hooks/
  hooks.json                # Event-driven hooks (SessionStart, PreToolUse, PostToolUse)
  session-check.sh          # Claude async env check (HASS_TOKEN, HASS_SERVER, python detection)
  env-guard.sh              # PreToolUse guard for Bash commands
  docs-check.sh             # Documentation validation
  docs-check.py             # Documentation validation helper
references/
  safety-invariants.md      # Core safety rules referenced by all skills
  settings-schema.md        # Settings file schema
  hass-cli.md               # hass-cli usage reference
  ha-web-ui.md              # HA web UI reference
  dashboard-api.md          # WebSocket API contract for storage dashboards
templates/
  templates.md              # Reference templates for generated configs