home-assistant-development

Developing for Home Assistant

This is code, not configuration. The consent rules still apply, and so does the rule that .storage/ and the other internal directories are off-limits.

Custom integrations

A custom integration lives at custom_components/<domain>/ and needs at least manifest.json and __init__.py. manifest.json carries domain, name, version, documentation, dependencies, codeowners, requirements, and iot_class — Home Assistant refuses to load an integration whose manifest is incomplete, and the error appears only in the log.

Points worth checking against the running version, because they change:

• Config-flow vs YAML setup — new integrations are config-flow only.
• async_setup_entry / async_unload_entry and the coordinator pattern (DataUpdateCoordinator) for anything that polls.
• Entity naming: _attr_has_entity_name and _attr_name interact in a way that has changed more than once.
• hass.config_entries.async_forward_entry_setups — the plural, awaited form.

Any change under custom_components/ needs a full Home Assistant restart. There is no reload for integration code. Say so, and ask.

Read the current developer documentation rather than recalling API shapes — get_integration_docs covers user-facing configuration, and https://developers.home-assistant.io is the reference for the code side.

Native LLM tool providers

Home Assistant has a native llm platform: Core and custom integrations expose curated tools through <integration>/llm.py and register an LLM API. Newer builds also serve those APIs over native MCP at /api/mcp/<API ID> — the built-in Assist API is /api/mcp/assist.

• get_ha_llm_development_guide returns the upstream references and a starter template for writing an llm.py provider. Use it before writing one.
• get_agent_capabilities (or the ha://agent/capabilities resource) reports whether the running instance actually has the native llm component, the registered API IDs/names from llm/api/list (2026.9+), the saved API selection, and which native MCP endpoints answer. Registration, endpoint initialization, and successful tool execution are separate checks. Discovery is read-only.
• This add-on cannot register tools with Home Assistant's llm platform. Registration is internal to integrations and custom integrations. What the add-on can do is consume a configured native LLM API over native MCP, which is what the optional homeassistant_native MCP server does.
• Native tools are curated by Home Assistant and are the better choice for requests that fit the configured API. The add-on's own MCP server is for configuration editing, safe writes, validation, admin and development workflows, screenshots, updates, ESPHome, hab, Zigbee, and documentation lookup.
• The generated starter code targets 2026.10.0b0: probatio.Schema, ToolResult, integration, ToolAnnotations, and domain-prefixed tool names. Use the matching release's source when supporting 2026.8/2026.9.
• New 2026.10 MCP Server entries expose all LLM APIs and require admin by default. That selection governs /api/mcp, not the individually keyed endpoints. Prefer assist for ordinary home control; a native rejection is not permission to retry through the add-on's broader administrative tools.
• Native MCP prompts are exposed as OpenCode commands (for example /homeassistant_native:Assist); discover the name for a custom/combined API. Read current context through the selected API's discovered native tool. MCP resource clients can also use homeassistant://assist/context-snapshot when advertised. Neither a retrieved prompt nor a snapshot stays current forever. Required arguments, titles, annotations and isError pass through the bridge; annotations do not override tool permissions. Legacy schema repair applies only to unprefixed GetLiveContext, not custom or modern schemas.