home-assistant - SKILL.md Agent Skill

name: home-assistant description: Inspect and troubleshoot Home Assistant for the home-server project. Use when the user asks about Home Assistant state, logs, entities, configuration, Lovelace storage, Matter, HomeKit, or related Docker runtime behavior. compatibility: opencode

Home Assistant

Home Assistant runs locally on this server via Docker. This is the opencode-server configuration, so all commands run directly without SSH.

Architecture

This server: Runs Home Assistant Docker container and all related services natively.

All runtime operations use direct Docker commands - no SSH needed.

Access Commands (Local)

Since Home Assistant runs locally, use direct commands:

# Check container status
docker compose ps homeassistant

# View recent logs
docker compose logs --tail=200 homeassistant

# Inspect container filesystem
docker exec homeassistant ls /config/.storage

# Restart Home Assistant
docker restart homeassistant

Discovering the Container Name

If the container name differs, discover it first:

docker ps --format "{{.Names}}" | grep -i home

Local Configuration vs Runtime

Configuration files (edit locally in this repo):

config/homeassistant/configuration.yaml - Main configuration
config/homeassistant/automations.yaml - Automations
config/homeassistant/scripts.yaml - Scripts
config/homeassistant/scenes.yaml - Scenes

Dashboards (storage mode):

Main dashboard (/lovelace): Uses Bubble Cards - stored in /config/.storage/lovelace.lovelace
Old dashboard (/old-home): Original pre-Bubble dashboard - stored in /config/.storage/lovelace.old-home
Edit by patching storage files directly and restarting HA

Runtime data (local):

/config/.storage/ - Entity registry, integration configs, state
/config/home-assistant.log - Runtime logs
Docker volumes and databases

Dashboard Philosophy

We use Bubble Cards for the primary dashboard interface:

Room cards (custom:bubble-card with card_type: button) - Quick access to lights, climate, media
Modal popups (card_type: pop-up) - Detailed controls for rooms, scenes, automations, system
Categorized automations - Bubble buttons grouped by function (Motion, Adaptive, BILRESA, Air, TV, Sync, Notifications)
Consistent interactions - Tap to toggle, hold for more-info

Dashboard modifications:

Backup: cp /path/to/homeassistant/.storage/lovelace.lovelace /path/to/backup
Create patch script to modify JSON structure
Apply patch: cat lovelace.bubble | python3 patch.py > lovelace.bubble.new
Deploy: cp lovelace.bubble.new /path/to/homeassistant/.storage/lovelace.lovelace && docker restart homeassistant
Verify: curl http://127.0.0.1:40104/lovelace returns 200

Deployment Workflow

Edit configuration files locally in config/homeassistant/
Commit changes to git
Deploy using the script (handles submodule updates and restart):
```
./deploy.sh
```

The deploy script will:

Pull latest Home Assistant configuration from the submodule
Create a backup automatically
Restart the Home Assistant container
Check for startup errors

Project Documentation

For complete project documentation including:

Full architecture overview
Port conventions (40xxx for web services, 21064-21065 for HomeKit, etc.)
Home Assistant YAML dashboard configuration guide
Troubleshooting common issues (mDNS, Matter, HomeKit)
Backup and restore procedures

See: AGENTS.md in the home-server repository

Key Technical Details

Lovelace dashboards: Storage mode, stored in /config/.storage/lovelace.lovelace
Matter Server: Native macOS service at ws://host.docker.internal:5580/ws
HomeKit: Uses scripts/homekit-mdns-proxy.sh for Bonjour advertisements on ports 21064 and 21065
Secrets: Never expose /config/secrets.yaml, .storage/, tokens, or backup contents
Backup location: backups/ directory (not committed to git)

Useful Commands (Local)

# Check HomeKit proxy status
./scripts/homekit-mdns-proxy.sh status

# View live logs
docker logs homeassistant -f

# Check Matter server
launchctl list | grep matter

# Validate YAML syntax
docker exec homeassistant python3 -c "import yaml; yaml.safe_load(open(\"/config/configuration.yaml\"))"

# List registered automation entities
docker exec homeassistant python3 -c "import json; data=json.load(open(\"/config/.storage/core.entity_registry\")); [print(e[\"entity_id\"]) for e in data[\"data\"][\"entities\"] if e[\"entity_id\"].startswith(\"automation.\")]"