An AI coding assistant working on your Home Assistant integration needs to know how config flows work. It can search the web, find a three-year-old forum post, and implement the API that was deprecated in 2023. Or it can read the actual docs.

The second option requires you to put the docs somewhere it can read them.

The Web Search Problem

AI assistants that can search the web will. And they’ll find things. Stack Overflow answers from HA 0.88. GitHub issues marked “fixed in core.” Medium posts from 2021 that are now quietly wrong about three things. The model doesn’t know which sources are authoritative; it doesn’t know what’s stale. It synthesises confidently from whatever it finds.

Local documentation is the fix. Actual markdown files that the AI can read directly. No latency, no invented APIs, no deprecated patterns presented as current best practice.

The Home Assistant project publishes everything you need as public GitHub repos: developer guides, config flow docs, 1400+ reference integration implementations, HACS publishing requirements. They’re all markdown. You can submodule them.

The Setup

Three submodules, shallow-cloned, under .submodules/:

.submodules/developers.home-assistant   # HA developer docs
.submodules/home-assistant.io           # HA user docs + 1400 integration examples
.submodules/hacs-documentation          # HACS publishing requirements

git submodule add --depth 1 \
  https://github.com/home-assistant/developers.home-assistant.git \
  .submodules/developers.home-assistant

git submodule add --depth 1 \
  https://github.com/home-assistant/home-assistant.io.git \
  .submodules/home-assistant.io

git submodule add --depth 1 \
  https://github.com/hacs/documentation.git \
  .submodules/hacs-documentation

Then set shallow = true on each entry in .gitmodules. Without this, anyone who clones the repo gets a full history fetch on repos that are, in home-assistant.io’s case, enormous.

[submodule ".submodules/developers.home-assistant"]
    path = .submodules/developers.home-assistant
    url = https://github.com/home-assistant/developers.home-assistant.git
    shallow = true

[submodule ".submodules/home-assistant.io"]
    path = .submodules/home-assistant.io
    url = https://github.com/home-assistant/home-assistant.io.git
    shallow = true

[submodule ".submodules/hacs-documentation"]
    path = .submodules/hacs-documentation
    url = https://github.com/hacs/documentation.git
    shallow = true

The submodules contain a lot of things that aren’t useful for integration development. Symlinks in a docs/ directory cut straight to the parts that are:

mkdir docs
ln -s ../.submodules/developers.home-assistant/docs docs/dev
ln -s ../.submodules/home-assistant.io/source/_integrations docs/integrations
ln -s ../.submodules/home-assistant.io/source/_docs docs/user-docs
ln -s ../.submodules/hacs-documentation/source/docs docs/hacs

docs/dev          -> HA developer guides (config flow, entities, architecture)
docs/integrations -> 1400+ integration reference pages
docs/user-docs    -> HA user documentation
docs/hacs         -> HACS publishing requirements and validation rules

docs/integrations/ is the directory that earns its disk space. Need to implement an entity platform you haven’t written before? There are dozens of official integrations that already do it. Grep for the pattern, read three or four, and the AI matches the established idiom instead of inventing something that looks plausible but isn’t.

Telling the AI About It

None of this helps if the AI doesn’t know the structure exists. You need to tell it. Add a section to your CLAUDE.md (or equivalent):

## Documentation

Relevant HA reference docs are available locally under docs/:

- docs/dev/          — HA developer guides. Start here for integration patterns.
- docs/integrations/ — Reference implementations for 1400+ official integrations.
- docs/user-docs/    — User-facing HA documentation.
- docs/hacs/         — HACS publishing requirements and validation.

Before implementing any HA pattern, check docs/dev/ first.
For examples of how existing integrations handle something, grep docs/integrations/.

### Key paths

- docs/dev/config_entries_config_flow_handler.md — config flow implementation
- docs/dev/core/entity/                          — entity platform base classes
- docs/hacs/publish/                             — HACS submission requirements

### Submodule commands

Clone with submodules:
  git clone --recurse-submodules --shallow-submodules <repo>

Update to latest docs:
  git submodule update --remote --depth 1

Why Bother

Ask an AI to “look up how HA config flows work” and it will find something. Whether that something matches the version of HA you’re targeting is an open question.

Local docs don’t drift. They’re pinned to whenever you last ran git submodule update; not today’s HEAD necessarily, but consistent and greppable. More than you can say for whatever the model absorbed from its training corpus.

One setup cost. After that, the AI reads before it writes.