hassio-addons: Instructions file for Claude Code

CLAUDE.md

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

Repository Overview

This is a Home Assistant add-on repository containing 120+ Docker-based add-ons for the Home Assistant Supervisor. Each add-on is a self-contained directory with a Dockerfile, config schema, and S6-overlay init scripts. The repository uses GitHub Actions for CI/CD, linting, and automated upstream version tracking.

Add-On Directory Structure

Most add-ons follow this common layout, though exceptions exist (e.g. some archived add-ons use config.json instead of config.yaml, some add-ons have build.yaml instead of build.json or no build file at all, and not every add-on includes a rootfs/ tree):

addon_name/
├── config.yaml          # HA add-on metadata, schema, ports, maps
├── build.json           # Base Docker images per architecture (may be build.yaml, or absent)
├── Dockerfile           # Multi-stage build (always uses shared .templates/ scripts)
├── updater.json         # Upstream release tracking; required to enable automatic updates
├── CHANGELOG.md         # Required; must be updated on every PR
└── rootfs/              # Optional; absent in some add-ons
    └── etc/
        ├── cont-init.d/ # S6-overlay init scripts (numbered, run in order)
        └── services.d/  # S6-overlay supervised services (some add-ons use
                         # s6-overlay v3 layout at etc/s6-overlay/s6-rc.d/ instead)

Dockerfile Convention

Most Dockerfiles follow this 6-section pattern (some add-ons deviate slightly, e.g. using a pinned upstream image directly instead of ARG BUILD_FROM):

1. Build Image – ARG BUILD_FROM + FROM ${BUILD_FROM}
2. Modify Image – S6 env vars, LSIO modifications via ha_lsio.sh
3. Install Apps – Copy rootfs/, download modules, install packages
4. Entrypoint – Set S6_STAGE2_HOOK=/ha_entrypoint.sh
5. Labels – Standard OCI + HA labels from build args
6. Healthcheck – curl-based check suppressed from nginx/apache logs