Heima — local-first home intelligence for Home Assistant
Hey everyone,
I have been working on a custom integration called Heima.
The short version: Heima is a local-first home intelligence engine for Home Assistant. It observes what happens in the home, learns recurring behavior, proposes automations or policies in plain language, and keeps checking whether accepted behavior still makes sense over time.
It is not meant to replace Home Assistant’s automation engine. Home Assistant is excellent at executing automations. Heima is an experiment in the layer above that: deciding what the home should probably be doing, based on observed behavior and explicit user approval.
How this is built
This project uses an LLM-assisted development workflow, and I would rather say that upfront than have it come out sideways in the comments.
I own the architecture, specifications, product direction, and review. LLM tools generate a lot of the implementation from those specs. I know that is a legitimate reason for some people to be skeptical, so two things about why I am doing it this way:
- I have not written production code by hand in a long time. Working this way is what makes it realistic for me to actually build something like this now, instead of not building it.
- I would rather ship something sub-optimal but working today than something theoretically optimal a few months from now. An idea that stays in a drawer does not get tested; usage in a real home is the only thing that tells you whether it is any good.
That trade-off is exactly why real-world testing and architectural feedback matter so much here. Whether the code is well-structured under the hood, whether it survives contact with a real home over months, and whether the underlying idea is sound — those are the parts an LLM cannot reliably judge on its own, and the parts I am most likely to get wrong without outside eyes on it.
Why I am building this
Most real HA installations slowly accumulate automations, scripts, helpers, blueprints, and one-off fixes. Each piece was reasonable when created, but over time they drift, overlap, or become hard to explain.
The new Home Assistant automation editor direction is very interesting here: automation authoring is becoming more natural and semantic. I think that is the right direction.
Heima is aimed at a different, complementary problem:
- HA helps you express automations better.
- Heima tries to reduce the number of automations you need to manually invent and maintain.
The goal is not “no configuration ever”. Installers still bind entities, configure domains, and review diagnostics. The goal is to replace brittle rule chains with learned, reviewable, lifecycle-aware behavior.
Roles
Heima is designed around two main roles:
- Installer / admin — configures the integration, binds entities, reviews diagnostics, and maintains the installation.
- Resident — lives in the home, receives proposals in plain language, accepts or rejects them, and can override behavior without touching configuration.
This role split is important. Many smart home systems effectively force residents into the developer seat. Heima tries to avoid that.
How it works
At runtime, Heima evaluates a deterministic domain pipeline:
People
-> Occupancy
-> Activity
-> House State
-> Lighting / Heating / Calendar / Security / other domains
-> Apply plan
The pipeline is event-driven from state_changed events with debouncing and a fallback polling interval.
On the learning side, Heima records local observations, runs analyzers, and generates reviewable proposals. Examples:
On weekdays around 08:00, this home usually transitions into "working".
Should Heima use this as a learned house-state context?
This lighting behavior appears to be recurring in the living room.
Should Heima create a reaction for it?
Accepted proposals become active behavior. Rejected proposals are remembered. Similar or superseded proposals can be grouped, dismissed, replaced, retired, or maintained through a proposal lifecycle.
Everything runs locally. There is no cloud learning service and no external ML runtime.
Current state
The project is now under the heima-labs GitHub organization.
I consider it still in pre-alpha state.
It is installable through HACS as a custom integration repository.
The v2 architecture (declarative domain/plugin DAG, replacing the old hardcoded v1 pipeline) has
been merged into main and is the active codebase, not just a design document anymore.
Development continues on top of it, phase by phase, on dedicated branches. Current implemented
areas include:
- deterministic runtime domain pipeline;
- built-in domain plugin DAG with
depends_onordering; - presence, occupancy, activity, house-state, lighting, heating, calendar, and security domains;
- local inference modules and snapshot history;
- behavior analyzers for patterns, anomalies, lifecycle suggestions, composite/cross-domain signals;
- approval-gated proposal engine;
- proposal grouping, temporal review bundles, replacement, retirement, and maintenance suggestions;
- outcome tracking: fired reactions are checked against expected outcomes;
- structural invariant checks for cross-domain consistency;
- manual-hold framework for respecting user intervention;
- admin-authored policy templates;
- camera privacy policies driven by alarm state and house-state conditions;
- resident runtime confirmation flow with auto-apply promotion once a reaction proves reliable;
- notification admin UI with per-route execution policy profiles;
- an in-HA admin observability panel explaining what Heima is doing and why;
- runtime checkpoint and power-loss recovery;
- diagnostics and live end-to-end test scripts against a Home Assistant test instance.
The repo currently has a maintained fake-house lab for seeded and live validation, plus local CI for unit tests, lint, formatting, and type-checking.
What is intentionally not done yet
Some things are still internal or experimental:
- The plugin architecture exists internally, but this is not yet a stable third-party plugin API.
- Contextual inference is currently based on local statistical confidence models, not a general ML system.
- Domain-specific admin tooling is still incomplete. Some policy editors exist, but broader tooling is still evolving.
- Per-person learning is not the main focus yet; current behavior is primarily home/room/context oriented.
How this differs from normal HA automations
Heima does not try to be another generic automation editor.
If the task is simply:
When sensor X changes, call service Y.
then the HA automation editor is the right tool.
Heima is more relevant when the task is:
Notice that this pattern keeps happening.
Propose it.
Group similar proposals.
Let the resident accept or reject it.
Retire or replace it when behavior changes.
Respect manual overrides.
Verify outcomes.
Surface diagnostics when domains disagree.
That is the space I am trying to explore.
Architecture notes
Some important concepts in the current codebase:
- Domain pipeline: deterministic per-cycle computation over normalized HA state.
- DomainResultBag: shared typed result container between domains.
- ProposalEngine: stores learned/admin-authored proposals and their lifecycle.
- Behavior analyzers: offline analysis producing typed findings and proposals.
- OutcomeTracker: records whether an applied reaction produced its expected effect.
- Invariant checks: per-cycle structural checks, debounced and reported through diagnostics.
- ManualHold: generic mechanism for pausing automation scope after user intervention.
- Admin-authored templates: domain-specific policy generation instead of raw generic automation editing.
There are extensive specs in the repo under docs/specs/, and the current v2 development plan is in docs/v2_dev_plan.md.
I am explicitly interested in feedback from people who understand Home Assistant internals, async integration patterns, diagnostics, and the difference between “nice demo” and “works in a real home for months”.
What I am looking for
Testers
People willing to install it in a non-critical HA environment and report where the model fails, where proposals are noisy, or where the runtime gets in the way.
Architecture feedback
Especially on:
- whether this kind of learning/proposal layer belongs inside HA as an integration;
- how semantic automation building blocks in newer HA releases should interact with a system like Heima;
- how far a custom integration should go in exposing domain-specific policy editors;
- whether the internal plugin contracts are shaped in a way that could later become a real extension surface;
- how to make diagnostics useful enough for installers, not just developers.
Contributors
Python + Home Assistant async patterns are required. The most useful contributions right now are focused fixes, tests, diagnostics, and architecture review.
Links
Organization:
Core integration:
Install:
HACS → Add custom repository → https://github.com/heima-labs/ha-heima-core → Integration
Specs:
docs/specs/ in the repo
Development plan:
docs/v2_dev_plan.md
Thanks for reading. I am happy to discuss design decisions, implementation tradeoffs, and where this overlaps or should integrate better with Home Assistant’s own automation direction.