Skip to main content

Events & automations

Home Keeper fires a Home Assistant bus event for every state change. Use these events to build automations. The events are:

ObjectEvents
Taskcreated, updated, completed, uncompleted, completion edited, deleted, armed, snoozed, due today set, skipped, overdue, no longer overdue, due soon
Partlow stock, out of stock, restocked
Appliancecreated, updated, deleted, archived, restored
Companionconnected, suggested

There are 3 ways to trigger on an event:

  • Select a Home Keeper trigger in the automation editor, such as Task became overdue or Spare part out of stock. See Triggers below.
  • Use the Event received trigger on the Home Keeper Events entity. See Events entity below.
  • Use a plain platform: event trigger on the event name.

Triggers​

Home Keeper adds 1 trigger for each of its events to the automation editor. The triggers work on Home Assistant 2026.1 and later. In Add trigger, find them in 3 places:

  • By target: select a device, an area or a label. The Home Keeper group lists the triggers for it.
  • By type: select Home Keeper under Integrations.
  • Search: type a word of the trigger name, such as overdue.

Add trigger, By target, with the Home Keeper triggers of an appliance

Add trigger, By type, with Home Keeper selected

A search for overdue finds the Task became overdue trigger

Target​

A task, part or appliance trigger needs a target. The target selects the tasks, parts and appliances that fire the trigger:

TargetThe trigger fires for
EntityThe task, part or appliance of the Home Keeper entity
DeviceThe tasks, parts and appliances on the device
AreaThe tasks and devices in the area, and each task with that area
FloorThe areas on the floor
LabelThe tasks with the label, and the entities, devices and areas with it
Home Keeper deviceAll tasks, parts and appliances

A task with no device has no entities. Target it by its area or its label, or select the Home Keeper device or the Home Keeper to-do list. The triggers for companions, declarative companions, data export and data import have no target.

The Task became overdue trigger with a device target

Home Keeper reads the target when the event fires. If a task moves to another device, the trigger follows the task. If you remove a device or a task, the trigger stops for it. The count next to the target in the trigger row can show 0. The trigger still fires for the tasks on that target.

The trigger variables hold the event as trigger.event, the same as a platform: event trigger. In YAML:

automation:
- alias: "Garage task overdue"
triggers:
- trigger: home_keeper.task_overdue
target:
area_id: garage
actions:
- action: notify.notify
data:
message: "Overdue: {{ trigger.event.data.name }}"

The trigger name is the event name without home_keeper_, such as home_keeper.task_completed or home_keeper.part_low_stock.

Device triggers​

The device triggers on a Home Keeper appliance and on a task device still work. Use the Home Keeper triggers for a new automation. In Home Assistant 2026.7 and later, Add trigger shows the device triggers under By type, Device. Home Assistant offers device triggers only for the 1 integration a device belongs to.

Events entity​

Home Keeper adds 1 Events entity, event.home_keeper_events, on the Home Keeper device. It gets all events, also for a task that has no device. The history of the entity shows each event. Home Assistant also puts each update of this entity in the logbook, so the logbook shows the Events entity next to the rows of the to-do list.

The Home Keeper device with the Events entity

Use it with the Event received trigger to get more than 1 event type from 1 trigger. The Event received trigger needs Home Assistant 2026.7 or later. In Home Assistant 2026.6, it is a Labs preview. In YAML:

automation:
- alias: "Any task done"
triggers:
- trigger: event.received
target:
entity_id: event.home_keeper_events
options:
event_type: [task_completed, task_skipped]
actions:
- action: notify.notify
data:
message: "{{ trigger.to_state.attributes.name }}"

The event type is the event name without home_keeper_. The attributes are the event data, without the large fields (source, managed_by, task_chips, active_season, note, photo and sections). Add a condition on the task_id attribute to select 1 task.

If an event fires while Home Keeper reloads, the Events entity can miss it. Adding a task to a device starts a reload. The Home Keeper triggers read each event from the bus, so they get every event.

An automation can add a part to the shopping list when the part goes out of stock. This is useful for a part without Auto-create buy task:

automation:
- alias: "Spare out of stock → shopping list"
trigger:
- platform: event
event_type: home_keeper_part_out_of_stock
action:
- service: todo.add_item
target: { entity_id: todo.shopping_list }
data:
item: "{{ trigger.event.data.part_name }} ({{ trigger.event.data.vendor }})"

The built-in shopping-list sync does this for a part already on auto-buy, and removes the line again when the part is restocked.

Events are edge-triggered. Home Keeper fires 1 event per transition and does not repeat it each cycle. Events are baselined on restart, so no overdue events are fired after a reboot. The full catalog with every event and payload is in docs/EVENTS.md.

Task history in the logbook​

Home Keeper writes a logbook row for each of these task events:

EventRow
Completedwas completed by Ann
Completed on an earlier daywas completed by Ann on 2026-10-20
Completed by a sensorwas completed by its sensor
Completion removedhad a completion removed
Completion of an earlier day removedhad its completion on 2026-10-20 removed
Skippedwas skipped
Snoozedwas snoozed until 2026-10-20
Due soonis due in 48 hours
Overduebecame overdue
No longer overdueis no longer overdue
Armedbecame due
Due today setwas set to due today
Occurrence movedhas its occurrence on 2026-11-01 moved to 2026-11-03

A completion row shows the day of the completion when it is not the day of the row. The day is in the time zone of Home Assistant. A change to the time of a completion writes 2 rows: the completion that is removed and the completion that is added.

Each row starts with the task name. The rows show in these places:

  • Activity in the sidebar, filtered to the Home Keeper to-do list
  • the logbook of the Home Keeper to-do list
  • the Activity card on the device page of the task, if the task has a device

The logbook text is in English. Created, updated and deleted tasks get no row on the to-do list.

A row also shows who made the change:

Change made byThe row shows
A user in the panel or on the to-do listThat user
The Complete button or a tag scanThe user who pressed or scanned
An action that a user callsThat user
An automation or a scriptThat automation or script
Home Keeper on its own, such as became overdueNo user

The is no longer overdue row names the user of the change that ended the overdue period, such as the user who completed the task.

The event has the same context. An automation can read the user from trigger.event.context.user_id. For a tag scan, the context has the user of the scan. Its parent is the scan. A change that Home Keeper makes on its own has a new context with no user. Examples are an overdue crossing and a change from a sensor.

The Activity page filtered to the Home Keeper to-do list, with a row for each task event

The Activity card on the device page of a water heater, with the completion of its task

Show the history on a dashboard​

A card that reads the logbook can show the rows. Use the logbook source of Chronicle Card with the to-do list:

type: custom:chronicle-card
title: Task history
days_back: 30
sources:
- type: logbook
entities:
- todo.home_keeper_tasks

All task rows are on 1 entity, the to-do list, so 1 source gets the rows of all tasks. The logbook can filter rows only by entity. To show 1 kind of row, filter on the text of the row. The Chronicle Card search filter keeps the rows that contain the text.

A task that becomes overdue gets a became overdue row. When it stops being overdue, it gets an is no longer overdue row. These changes end the overdue period:

  • a completion
  • a skip
  • a snooze
  • a move of its date to the future
  • a disable of the task
  • a clear by its sensor

Both rows contain the word "overdue". So this card shows when each task became overdue and when it stopped:

type: custom:chronicle-card
title: Overdue tasks
days_back: 30
sources:
- type: logbook
entities:
- todo.home_keeper_tasks
filters:
search: overdue

Use search: was completed for the completions. search takes 1 text, so use 1 card for each kind of row.

The logbook keeps the rows for as long as the recorder keeps its data. The default is 10 days. To keep the rows longer, set purge_keep_days:

recorder:
purge_keep_days: 90

The recorder keeps the task events only if it keeps the Home Keeper to-do list. If your recorder exclude has the todo domain or the to-do list, the logbook shows no rows.