Dedicated Core integration for the official companion apps (successor to mobile_app) #248

Problem statement

The mobile_app integration was designed years ago to generically serve any mobile app, before Core had strict entity descriptions and today's integration patterns. It is now the entry point for our two most important user surfaces — the official Android and iOS companion apps — but its design actively blocks us from delivering the experience we want:

• The app, not Core, defines the entities. It works like MQTT discovery: the app pushes entity definitions and Core just renders them. Core cannot control the shape of what is inside it, cannot migrate users, and changes in Core are very hard to adopt because we don't know what each app version is doing. The Android app alone can create thousands of entities.
• Everything must stay generic, so platform-specific features (e.g. Live Activities on iOS, Android-only commands) cannot be exposed in a first-class, tailored way.
• Features are hidden behind "magic strings" in notification data (actionable notifications, notification commands, Live Activities). Users copy YAML from docs, get it slightly wrong and spend hours troubleshooting. There is no validation, no discoverability, and the notification documentation is split between the iOS and Android companion docs with different structures.
• Backwards compatibility is ad hoc. Apps and Core are versioned independently and keep compatibility through hacks on both sides.
• State synchronization is fragile, e.g. disabling an entity in Core doesn't reliably stop the phone from sending updates and draining battery; enabling/permission of personal sensors is handled inconsistently.
• Contributions are being held back because there is no agreed target architecture; maintainers don't want to keep piling features onto mobile_app.

Who is impacted: every companion app user (the largest entry point to Home Assistant), the iOS/Android app maintainers, Core/frontend maintainers, and third-party app developers who currently build on mobile_app.

Why it matters to OHF: our own apps should offer the best possible Home Assistant experience. Today we can neither shape that experience from Core nor make powerful mobile features (notifications, Live Activities, device commands) approachable in the automation editor.

Community signals

Internal: in-person alignment session (September 2026) between the iOS and Android app maintainers and Core maintainers, called because "where mobile configuration lives and why it's done this way" has been a recurring source of friction and blocked contributions for years.

Community: recurring confusion and support load around notification YAML / notification commands / actionable notifications (forum, Discord); third-party companion-style apps increasingly building on mobile_app because it's the only way to get the same experience as the official apps. Links to be added.

Scope & Boundaries

In scope

• A new Core integration (working name companion) purpose-built for the official Home Assistant companion apps (iOS and Android), written with our apps in mind. Others may use it, but we do not commit to serving third-party apps and may decline contributions that only target other apps.
• A versioned, specified schema for app ↔ Core communication (capabilities, sensors, commands, notifications). Both sides advertise supported schema versions and negotiate the highest common one.
• Core owns entity shape, presentation and translations; apps report capabilities and values ("ahead-of-time" knowledge of all potential sensors in Core).
• Platform-specific features are allowed (iOS-only / Android-only actions) next to shared actions; capability / feature flags on devices so targets and actions can be filtered.
• Proper actions and entities (with a tailored UI) for notifications, actionable notifications, notification commands and Live Activities instead of magic strings.
• Seamless migration from mobile_app, driven by the app upgrade; users should not have to know they migrated. mobile_app and companion coexist during the transition.
• Merge the companion app documentation into the Home Assistant documentation (with a way to track app-version vs Core-version dependencies).
• Fix enable/disable and permission synchronization of sensors between app and Core.

Not in scope

• Extending the mobile_app backend further. It is feature-frozen; existing hacks (e.g. notification data) keep working until migration is complete.
• Changing the transport (WebSocket/REST + push notifications stay; peer-to-peer, VPN etc. are separate topics for later).
• A generic "device type" filter / target picker for all integrations (this opportunity may inform it, but does not solve it).
• Automating personal sensors from Core (e.g. enabling location tracking on someone else's phone). The user, in the app, stays in control; Core may at most request.
• A committed timeline.

Foreseen solution

• One new domain, companion, hosting both iOS and Android (decision: one integration, not two — can be split later if it becomes a mess). A shared base with helpers for common functionality, and platform-specific code where needed. From the user's perspective there is a single list of "my mobile devices" tied to their user account, each with its capabilities.
• Capability / feature flags per device (platform, supported features). Every action registers the capabilities it needs; the target picker only shows compatible devices, and platform-only actions say so in their name. Shared actions (e.g. send notification) accept targets from both platforms.
• Core-controlled, versioned schema (inspired by how Matter/Z-Wave handle this, and by the parts of mobile_app that work well): Core knows up front which sensors and commands can exist; the app reports which are available/enabled on this device and their values. Core presents them; unavailable ones are not created, disabled ones are just disabled. Schema versions are negotiated on connect; Core stays backwards compatible across versions and can tell the user in the UI when an app is too old/new for a feature.
• First-class notification & command experience: extend the notification entity in Core with the most important mobile features, and add dedicated actions (actionable notifications, Live Activities, device commands) with custom frontend UI tailored to the selected targets, so users pick instead of copying YAML.
• Personal sensors & permissions: the user opts in from the app; Core can request enabling a sensor, which the app prompts for and decides on (never silently enabled from Core).
• Migration: app upgrade registers the device on companion and migrates the mobile_app entry; apps keep supporting older Core versions. Ship incrementally behind opt-in, gather feedback, don't force-migrate until we're comfortable.
• Documentation merged into the main HA docs.

Risks & open questions

• The communication schema / spec is the first and biggest thing to define — it determines everything else. Who writes it, what format, how it is versioned, and what we copy from existing patterns (Z-Wave/Matter negotiation; no existing integration is a perfect template).
• One vs. two domains: if iOS and Android features keep diverging (e.g. Live Activity fields that share names but behave differently), a single domain risks ending up with copy-paste YAML anyway. Mitigation: capability flags now, split later if needed. Conversely, separate APIs could lose the ability to send one action to both platforms.
• Frontend work: a capability-aware target picker and tailored action UI does not exist yet; device-type filtering does not exist either. Is this a companion-specific exception in the frontend or a general mechanism all integrations benefit from?
• Migration seamlessness: users must not notice; how long do mobile_app and companion coexist, and how long do apps support old Core versions?
• Documentation merge vs. independent app versioning: features don't all depend on Core releases; how do we track "requires app version X" in the HA docs?
• Entity noise: ~200 potential sensors per phone. How do we present available-but-disabled vs. not-available-on-this-device, and how does the app onboarding (categories / groups of sensors) look without 200 checkboxes?
• Privacy & permissions: who may enable which sensors (never another user's phone from Core); how requests from Core are surfaced on the device.
• Third-party apps currently on mobile_app: what do we tell them, and what happens to mobile_app long term (deprecate, then measure usage in a year or two)?
• In-flight contributions against mobile_app are on hold unless they only use already-existing paths.
• Effort: this is close to a rewrite of the app ↔ Core layer on both apps and Core; it cannot be done in one shot and needs phases.

Appetite

Large — multiple cycles across core, frontend, iOS and Android. Suggested phases: (1) define and agree the communication schema/spec; (2) new companion integration in Core plus app implementations, shipped behind opt-in alongside mobile_app; (3) notifications/actions UX and frontend target picker; (4) migration, deprecation of mobile_app and documentation merge. We want to open this up and invite contributors to help once the spec is defined.

Execution issues

No response

Decision log