Skip to main content

Integrating with Home Keeper

This guide is for authors of other Home Assistant integrations that push recurring tasks into Home Keeper, such as a battery, plant or pet integration. Your integration owns the schedule. It uses only the event bus and services, with no Python import and no hard dependency. The 1 exception is a panel tab (§10), which is a Python API. Home Keeper stores and echoes the source and origin values verbatim. Only the completion gates read origin.

Every action, field, event and payload is in the generated API reference. The event catalog is in EVENTS.md.

Rules for every integration:

  • Guard every call with hass.services.has_service("home_keeper", "<service>"), so your integration works when Home Keeper is absent.
  • When the Home Keeper config entry reloads or is disabled, a call raises HomeAssistantError with the translation key integration_not_loaded. Catch it where a failed call must not stop your code, and try again on home_keeper_register_companions (§9).
  • Use ids, not names. Each task_id, asset_id, part_id and document_id field also accepts a name for hand-written YAML, but a name can change and is not unique.

1. Creating a task​

Recurrence is floating (interval + unit, from the last completion) or fixed (rrule + anchor). The older freq + interval for a fixed task still works. Keep the returned task_id:

DOMAIN_HK = "home_keeper"

if hass.services.has_service(DOMAIN_HK, "add_task"):
resp = await hass.services.async_call(DOMAIN_HK, "add_task", {
"name": "Replace smoke-detector battery",
"notes": "Uses a **9V** battery.", # Markdown source, stored verbatim
"recurrence_type": "floating", "interval": 6, "unit": "months",
# Fixed: "recurrence_type": "fixed", "rrule": "FREQ=MONTHLY;BYDAY=1TU",
# "anchor": "2026-01-06T08:00:00"
"last_completed": "2026-01-01T08:00:00", # optional; else the task is due now
"device_id": my_device_id, # optional device registry id
"source": {"my_integration": {"thing_id": thing_id}}, # namespaced under YOUR domain
}, blocking=True, return_response=True)
task_id = resp["task_id"]

With a device_id, the next-due sensor, overdue binary_sensor and mark-done button show on that device page. Get the id with async_get_device_by_identifier (Home Assistant 2026.9+).

Find a task again after a restart. Call list_tasks with return_response=True, then match on your source namespace. Put a unique id of your own, such as a schedule_id, in source. Put a device id at the top level of your namespace, under the key device_id. When Home Assistant renumbers a device, Home Keeper heals only the task device_id and source.<your-namespace>.device_id. Another place is not healed, and your next reconcile makes a duplicate.

2. Reacting to a completion​

Home Keeper fires home_keeper_task_completed on every completion, from every surface. These include the to-do checkbox and the device button, the panel and the complete_task service.

@callback
def _on_hk_completed(event):
if event.data.get("origin") == "my_integration":
return # the echo of our own completion (§4)
if src := (event.data.get("source") or {}).get("my_integration"):
hass.async_create_task(_record_done(src, event.data.get("completed_at")))

entry.async_on_unload(hass.bus.async_listen("home_keeper_task_completed", _on_hk_completed))

The payload has task_id, name, source, completed_at, origin (None for a user), managed_by, and the common task fields.

3. Completing from your side​

Call home_keeper.complete_task with task_id, an optional completed_at, and origin: "my_integration". For an undo, Home Keeper fires home_keeper_task_uncompleted, whose ts names the removed completion. To undo from your side, call home_keeper.delete_completion with task_id, that ts and your origin.

4. Two-way sync and loop prevention​

A call you make comes back to your listener as an event. Use two guards to stop a loop:

  1. origin marker. Send your own origin. Your listener ignores events with it.
  2. No completion on the inbound path. When your listener reacts to an event, write your record through a code path that does not call complete_task or delete_completion.

5. Lifecycle​

  • Your config is removed: call home_keeper.delete_task for the ids you stored. A call for an id that is already deleted succeeds. A name that matches no task fails with task_not_found.
  • The user deletes a task in Home Keeper: home_keeper_task_deleted fires with your source. Also reconcile at setup with list_tasks, for deletions while you were stopped.

6. Declaring managed ownership (optional)​

Pass managed_by with source on add_task to declare your integration as the owner of a task. Home Keeper reads managed_by and acts on it.

FieldEffect
integrationRequired. Your domain.
display_nameRequired. A Managed by {name} chip on the task card and page.
iconAn mdi: icon.
locked_fieldsThe panel removes these fields from the edit form. With every field locked, the task page shows no Edit button.
config_entry_idOrphan detection, and an Edit in {name} link on the task page.
completion_promptA short hint near the Done button.
completion_blockedNo surface offers Done. complete_task and skip_task accept the task only with your domain as origin. Use it only for a read-only mirror.
deletion_protectedThe panel shows "Delete from {name} instead", and delete_task rejects the call while your entry is loaded. Requires config_entry_id.
  • Set managed_by once, on add_task. The update_task service has no managed_by field, so a call that sends one fails validation.
  • Home Keeper removes the locked fields from every update_task payload, also from your own calls. A locked field keeps the value it had at creation. Lock only the fields your integration never changes. To change one, delete the task and add it again.
  • photos cannot be locked. Photos belong to the household, like the stock of a managed part, so users can always add, remove and reorder them.
  • add_task rejects deletion_protected without config_entry_id (invalid_task), because Home Keeper then cannot see that your integration is gone.

Cleanup. When the recorded config entry is not loaded, the task is orphaned. The chip shows Integration offline and Delete comes back. The task list also offers Remove orphaned tasks (home_keeper.delete_orphaned_tasks, admin-only). As a last resort, delete_task with force: true ignores the protection.

7. Condition-driven (triggered) tasks​

For work that a condition starts, such as a low battery or a wet water sensor, send recurrence_type: "triggered" and no schedule fields. A triggered task is armed (next_due is a time and the task is overdue on every surface) or dormant (next_due is null and the task shows only in the panel Monitored section).

add_task creates the task armed. When the condition resolves, complete_task records a completion and makes the task dormant. Send your domain as origin. When the condition comes back, trigger_task arms it again. Both calls are idempotent. Keep one task per monitored thing and toggle it, so that the id and the history stay.

Sensor-based tasks​

With recurrence_type: "sensor" and a sensor mapping, Home Keeper watches an entity and arms the task itself (home_keeper_task_triggered). The task starts dormant.

# Usage: due when the reading advances by `target` since the last completion.
"sensor": {"entity_id": "sensor.x1c_total_usage_hours", "mode": "usage", "target": 300,
"unit": "h", # display label only
"also_every": {"interval": 6, "unit": "months"}, # time backstop
"combinator": "any", # or "all"
"baseline": 660} # else the first reading
# Threshold: due when the reading crosses the comparison for for_seconds.
"sensor": {"entity_id": "sensor.airflow", "mode": "threshold",
"comparison": "<", "value": 60, "for_seconds": 120}

The also_every backstop applies also when the entity is unavailable. home_keeper.set_task_meter moves the baseline. A completion records the live value as reading. To mirror earlier work, send reading on complete_task, and send it again on each update_completion, which clears a key that you omit.

Task chips​

task_chips on add_task or update_task puts chips on the task in the panel and the card. Each chip has label (required), icon (an mdi: name) and url (http(s)://). update_task changes the chips only when the call sends task_chips. Users cannot edit chips. Do not send a chip for a linked part, because Home Keeper draws that chip (§8).

8. Managing an appliance​

Send managed_by and source to home_keeper.add_asset to own an appliance and its parts. Its block is the task block without completion_prompt and completion_blocked. Both fields are create-only: update_asset ignores source, and accepts managed_by only as null. Find your appliance again with home_keeper.list_assets.

Locked parts​

The vocabulary is const.ASSET_LOCKED_FIELDS. Each field except parts works as on a task. A locked parts splits each part: the owner keys are yours, the stock keys are the user's.

Owner keys (locked)User keys (never yours)
name, type, notes, part_number, vendor, url, coststock, reorder_at, stock_unit
replace_interval, replace_unit, replace_also_every, actionconsume_quantity, create_buy_task
use_noun, use_task_name, last_replaced, carried_usesrestock_quantity

update_asset writes only user keys, on parts that exist. To write owner keys, call home_keeper.update_managed_asset (admin-only, your appliances only) with asset_id, an optional name, and the full parts list. Parts match on id. A part without a known id is new and starts at stock: null. Do not send stock, because Home Keeper drops it. A part you leave out is removed only if it tracks no stock. To name the devices that use shared stock, write a "Used by" line in the part notes.

Stock and source​

home_keeper.set_task_consumable sets the parts of a task in a parts list of {asset_id, part_id, quantity}. It replaces the links. parts: [] unlinks. The old asset_id, part_id and quantity fields log 1 warning per run. They will be removed in a later release. A completion takes quantity (default: the part consume_quantity) off each part. The links are in source["parts"] and in the task events. The load moves an old source["part"] link with manual: true into that list. A completion keeps 1 stock_drawn record for each part. delete_completion gives each back. Each part fires its stock event.

For a use that is not a task, call home_keeper.adjust_part_stock with a negative delta. The response is {stock, applied_delta, reorder_at, unit, status}. To undo, send applied_delta back negated, because it differs from delta when the count stops at 0. Each counted part on a virtual appliance has a spares number entity, home_keeper_asset_<asset id>_part_<part id>_stock, which all users can read.

source is a map of namespaces. Home Keeper owns part, buy and declarative_companion. Merge into source and remove only your own key. On update_task, each namespace in the call replaces the stored one, null removes it, and a reserved name fails with invalid_task.

Uninstall. A delete of a managed appliance deletes the user's stock counts. In async_remove_entry, call update_asset with {"asset_id": asset_id, "managed_by": None}. The locks come off and the user keeps the appliance. Delete it only when no part tracks stock.

9. Discovery and declarative companions​

Call home_keeper.register_companion at setup to show your integration in the panel Settings → Companions section. Call it again on home_keeper_register_companions, which Home Keeper fires at its own setup and reload.

The service is admin-only. A call from your setup or from the event listener has no user, so it passes. Do not pass the context of a user to it.

await hass.services.async_call(DOMAIN_HK, "register_companion", {
"domain": "my_integration", "name": "My Integration", "icon": "mdi:puzzle",
"description": "One line on what it does with Home Keeper.",
"config_entry_id": entry.entry_id, "docs_url": "https://github.com/me/my-integration",
}, blocking=False)

Registering fires home_keeper_companion_connected.

A declarative companion makes one managed sensor task for each entity that matches a selection. Users make them in Settings → Companions → Declarative. An integration can call add_declarative_companion, update_declarative_companion, delete_declarative_companion and list_declarative_companions (all admin-only).

  • Select by target_integration and selection.translation_keys in preference to entity_regex: a translation key does not change on a rename or a language change. selection.device_ids limits the selection to those devices.
  • task_template.task_names maps a key to a name, read as {{ task_name }}.
  • A call returns after the reconcile, and after a config entry reload if one is necessary.
  • Find these tasks by managed_by.integration == "home_keeper" and source.declarative_companion.spec_id. A Profile selects them with home_keeper:declarative:<spec_id>.
  • The presets are in declarative_presets_catalog.py. An integration preset id is <domain>_<shape>, such as roborock_life_low.

Write a glue integration instead when you must write back to the upstream integration on completion, or keep state across completions. See GLUE_INTEGRATIONS.md.

10. Add a panel tab​

A companion integration can add an admin tab to the Home Keeper panel at /home-keeper/<id>/.... The tab runs JavaScript in the admin panel. So only Python code in the Home Assistant process registers a tab. The register_companion service does not accept a tab.

In your manifest.json put http in dependencies and home_keeper in after_dependencies. Then your config flow can tell the user to install Home Keeper. At setup import panel_tabs in a try block and create a repair issue if the import fails.

from pathlib import Path

from homeassistant.components.http import StaticPathConfig

from custom_components.home_keeper.panel_tabs import PanelTab, async_register_panel_tab


async def async_setup_entry(hass, entry):
if not hass.data.get("my_integration_static"): # a static path stays for the run
await hass.http.async_register_static_paths([StaticPathConfig(
"/my_integration_static", str(Path(__file__).parent / "www"), False)])
hass.data["my_integration_static"] = True
unregister = async_register_panel_tab(hass, PanelTab(
companion="my_integration", id="library",
titles={"en": "Library", "de": "Bibliothek"}, icon="mdi:bookshelf", # "en" is required
module_url="/my_integration_static/library-tab.js?v=1", # change v on each release
element="home-keeper-library-tab", host_api=1, order=100)) # the defaults
entry.async_on_unload(unregister)
return True
  • id matches ^[a-z][a-z0-9-]{1,30}$ and is not in panel_tabs.RESERVED_TAB_IDS.
  • module_url is a same-origin path of at most 500 characters: 1 leading /, no scheme, no backslash and no .. segment. element starts with home-keeper-.
  • The entry of the tab is in the tab bar now. A later release can move it to a menu or a launcher, and order is only a hint. Make the page work from any entry.
  • A tab that is not valid, or a second tab with the same id, raises ValueError with the reason. The unregister callable is idempotent.
  • A reload of Home Keeper keeps the tab. Call register_companion too (§9): the switch that hides the tab is on your companion row in Settings → Companions.

On the first open of the tab, the panel imports the module and makes 1 element. The element stays while the panel is open. A redraw moves it, so connectedCallback can run more than once. The panel sets these properties and keeps them current:

interface HomeKeeperTabElement extends HTMLElement {
hass: HomeAssistant; // on every update
narrow: boolean;
route: { path: string }; // the part after /home-keeper/<id>: "" or "/books/12"
host: HomeKeeperTabHost; // set 1 time
}
interface HomeKeeperTabHost { // host API version 1
readonly apiVersion: 1;
navigate(path: string, opts?: { replace?: boolean }): void; // to /home-keeper/<id><path>
taskLink(taskId: string): string; // the panel URL of a task page
applianceLink(assetId: string): string; // the panel URL of an appliance page
openTask(taskId: string): void; // open the task page, with no page load
openAppliance(assetId: string): void; // open the appliance page, with no page load
showToast(text: string): void;
}

Move inside the tab only with host.navigate. Do not write to history. Use taskLink and applianceLink for an href. The panel opens a plain left click on a link to /home-keeper/... with no page load. A click with a modifier key, a target or a download attribute, or a click that the tab handled, goes to the browser. For a host_api that is higher than the panel supports, the panel asks the user to update Home Keeper. An import that fails or takes more than 10 seconds gives an error with Retry.

11. Join the export and import​

The Home Keeper export can hold the data of your integration. Then a user does 1 export and 1 import for all of it. Your data goes in a top-level section with the key of your domain. Home Keeper stores your export response there as is, and does not read it.

  1. Add import_export to capabilities in register_companion (§9).
  2. Make 2 admin-only services that return a response. Check admin in each service, because a user can call them directly. Home Keeper calls them with the context of its caller.
ServiceFieldsResponse
<domain>.export_datafiles_dir (optional){format, version, data, skipped}
<domain>.import_datadocument, dry_run, files_dir (optional){ok, dry_run, counts, records, problems}
  • format is an integer that you own. Increase it only when the meaning of a key changes. Refuse a document with a higher format. skipped maps a name to a count.
  • document is your section as the export returned it. The user can edit it and import it on a different install. Import is an upsert: match by your id, then by a natural key such as a name. Never delete a record that is not in document.
  • problems is a list of {level, path, message}. level is error or warning. path starts in data, such as dogs[2].name. An error blocks the whole import.
  • With dry_run: true, write nothing and return the report. Home Keeper does a dry run of every section first. It applies a section only if all of them are clean.
  • files_dir is set only for a bundle (a .zip export). On export, copy your files into it and put the relative paths in data. On import, read them from it. Refuse a files_dir that is not below .storage/home_keeper_import_export/, and refuse a relative path with ... Home Keeper skips a symbolic link in it.
  • Each call has 300 seconds. When an export fails, Home Keeper puts failed in skipped.companions of its envelope. When an import fails, your section gets an error.

Make the data portable:

  • Do not export an id that only one install knows, such as a Home Keeper task id or a to-do item uid. Your reconcile makes them again.
  • Next to a person, area or entity id, export its name. On import use the id if it exists, else the name, else return a warning.
  • Home Keeper does not export a task that has managed_by. Make your managed tasks again after the import, in your normal reconcile.

Home Keeper imports its own sections first, then each companion in the order of registration. A companion that is not installed, or that has no import_export, gets a warning and is skipped. The import report has your report under sections.<domain>, and your problems in problems with the path <domain>.<path>.

Testing your integration​

Add home-keeper @ git+https://github.com/prestomation/ha-home-keeper@main to your test requirements, and use the fake with pytest-homeassistant-custom-component:

from home_keeper.testing import async_setup_fake_home_keeper

async def test_two_way_sync(hass):
hk = await async_setup_fake_home_keeper(hass) # registers the real service names
# ... set up your integration so it calls home_keeper.add_task ...
task = hk.get_task_by_source("my_integration", thing_id="abc")
hk.fire_user_completion(task["id"]) # a user completion, origin=None
await hass.async_block_till_done() # then assert your record, with no loop

FakeHomeKeeper also has .tasks. It uses the real model, recurrence and event payload code (home_keeper.events.completion_event_data), so it cannot drift from production. Pawsistant is one client of this contract.