Chore Helper - Track recurring or manual chores with flexible scheduling

[ben.mcclure]

I’ve released an integration to help manage household chores and thought I would share it with the community.

GitHub - bmcclure/ha-chore-helper: A Home Assistant helper integration for...

Chore helper has had several feature releases lately and has been stable for me, though I don’t have much feedback from other users yet. Version 0.5.0 was just released with additional features and bug fixes.

This integration adds a new Helper to Home Assistant named Chore. Chores are heavily inspired by and originally based on the Garbage Collection integration, so scheduling them works in a fairly similar manner with additional options.

Example chores you could create:

• “Mow the lawn” - 2 weeks after it was last mowed, only on Saturdays, starting in April and ending in November
• “Change the HVAC filter” - 1 month after it was last changed, marked complete by an automation listening to the state of a contact sensor on your filter cover
• “Pay bill” - scheduled manually via automation for 2 weeks after you get a bill notification email from the provider
• “Clean my hard drive” - scheduled via automation when your hard drive space is above 70%, marked complete via automation when your hard drive space drops below 60%

There is absolutely nothing wrong with the Garbage Collection integration, it’s wonderful, however Chore Helper can also be used for garbage collection if you don’t want to use both integrations. Just note that there are a few differences currently in how you would set it up in Chore Helper:

1. Given that you’re tracking the chore to put the garbage out, not the actual collection, I’d recommend making the due date 1 day before collection.
2. Unlike Garbage Collection, chores don’t complete themselves automatically. You can use an automation that completes the garbage collection chore when the state is -1, since that means your garbage collection is over and would advance it to the next date.

The idea behind this integration is to recreate the basic functionality that I use from the Tody app on my phone in Home Assistant so that the data can be available on my home displays, used in automations and notifications, and shown in a calendar view. Grocy offers chore scheduling as well, but a home ERP is a bit heavy of a solution for my needs, and I wanted to see if I could make something purely as a Home Assistant component.

Chores can be scheduled to recur “every N days/weeks/months/years” (scheduled based on start date), “after N days/weeks/months/years” (scheduled based on completion date), or can be scheduled manually via a service call. Each type of scheduling offers different options available in the UI, such as week numbers and days of the week for monthly chores. The options can be updated at any time.

A chore calendar is automatically created containing events for the next due date of each chore, as well as projected future due dates. Chores have a setting to be hidden from the calendar as well.

Unlike Garbage Collection, chores are never completed automatically, only by calling the “chore_helper.complete” service. This means that chore due dates can be in the past, signifying an overdue chore. The main state is a positive or negative number of days away from the due date, and there are attributes indicating the next due date, the last completion date, whether the task is overdue, the number of days overdue, as well as any active date offsets, manually-added dates, and manually-removed (e.g. skipped) dates.

There are services for completing a chore, adding a manual date to a chore, removing a date from a chore (e.g. skipping a due date), offsetting the due date of a chore by a number of days, and triggering an update of the state of a chore.

Icons can be set for each chore in various states so you can visually see what’s in the future, due tomorrow, due today, or overdue.

There is a known issue I haven’t resolved yet related to how bare dates show in the Home Assistant UI–they always appear a day early for some reason, even though the underlying value is correct and shows up right on the calendar. For example, the due date in the screenshot below is actually 4/10/2023, but it shows as the 9th within the attributes. I don’t know why this happens yet.

I’m actively working on better documentation as well as implementing missing functionality and considering some new ideas, such as:

• Optional due times so that a chore can be due at a certain time on the due date
• The concept of chore assignments (still working out how this should function)
• A device for each chore which encapsulates additional entities, such as buttons for completing or skipping a chore so that you can use the integration without manually calling services
• An option to show overdue tasks on today’s calendar date

I will also be working on a Chore Cards repository soon, offering ready-made cards for single chores as well as lists of chores.

Feel free to weigh in with your thoughts on these ideas, or your own ideas!

I’ve been using Auto Entities to create filtered cards of chores with a tap action of calling the complete service. It works quite well! Here is a screenshot of the cards in action the code that creates them:

There would be an Overdue card here if I had overdue chores to show. Also, I’m using card themes for slight color differences in this example, but I didn’t include them in this code for portability

- type: custom:auto-entities
  card:
    type: entities
    title: Overdue
  filter:
    include:
      - integration: chore_helper
        state: "< 0"
        options:
          tap_action:
            action: call-service
            service: chore_helper.complete
            service_data:
              entity_id: this.entity_id
  sort:
    method: state
    numeric: true
  show_empty: false
- type: custom:auto-entities
  card:
    type: entities
    title: Today
  filter:
    include:
      - integration: chore_helper
        state: "= 0"
        options:
          tap_action:
            action: call-service
            service: chore_helper.complete
            service_data:
              entity_id: this.entity_id
  sort:
    method: state
    numeric: true
  show_empty: false
- type: custom:auto-entities
  card:
    type: entities
    title: Upcoming
    state_color: true
    show_header_toggle: true
  filter:
    include:
      - integration: chore_helper
        state 1: "> 0"
        state 2: "<= 7"
        options:
          tap_action:
            action: call-service
            service: chore_helper.complete
            service_data:
              entity_id: this.entity_id
  sort:
    method: state
    numeric: true
  show_empty: false

Screenshots:

Note: You can name the chores whatever you want when first creating them, the name field is just not available when editing existing chores.

[Tarusky80]

Hi, is it possible to set it to tell me 5 days before, how many days until the last wednesday of the month?

[ben.mcclure]

That’s an interesting challenge!

You can set a chore for the Nth Wednesday of the month, or the Wednesday of the Nth week of the month, but I don’t think there’s currently a way for a chore to be pinned to the last Wednesday of the month.

I think that’s a good idea for a new feature. I will test out adding an option to select the last week of the month for a monthly chore, it sounds fairly straightforward to implement.

Beyond that, once you can set a due date for the day you want, the chore sensor’s state will always be the number of days until (or since) the next due date, so you could set up an automation to notify you when the chore state is “5”, and then you could set an automation that automatically completes the chore on the due date so that it advances to next month.

(Note: I’m also planning to add an option to automatically complete a chore on the due date which could avoid needing that extra automation)

Update: I’m trying to decide what the best implementation of this new option should be:

1. Allow you to select “last” for the week of the month, or
2. Allow you to select negative numbers for the week of the month, which would count backward from the end of the month instead of forward from the beginning

I’m leaning toward #2, because it seems more flexible, although not quite as simple of a UX.

[ben.mcclure]

I have a new answer to your question in the form of version 0.3.0 of Chore Helper:

Release Chore Helper 0.3.0 for Home Assistant · bmcclure/ha-chore-helper

You can now choose “last”, “2nd from last”, “3rd from last”, or “4th from last” as week options for monthly chores, and it works for both types of week scheduling (Nth weekday of month, or weekday of Nth week of month).

If you need any guidance on how to create an automation to notify you based on the chore, or if you run into any trouble with this, let me know!

[Tarusky80]

Could I see some screenshots of how it’s configured?
Thank you

[ben.mcclure]

Sure! Here are screenshots of me creating a chore for the last wednesday of every month, and after that I will paste an automation that both notifies you 5 days before, and also automatically completes the chore after the last wednesday so that the next due date becomes the following month.

Note there is a minor bug with how the Next Due Date displays inside the sensor attributes–it shows the previous day, but the actual date is 4/26 so it’s just a display bug. I’m looking into this, but it doesn’t affect any calculations.

Automation:

description: ""
mode: single
trigger:
  - platform: state
    entity_id:
      - sensor.last_wednesday_of_month
    to: "5"
  - platform: state
    entity_id:
      - sensor.last_wednesday_of_month
    to: "-1"
condition: []
action:
  - choose:
      - conditions:
          - condition: numeric_state
            entity_id: sensor.last_wednesday_of_month
            below: 0
        sequence:
          - service: chore_helper.complete
            data: {}
            target:
              entity_id: sensor.last_wednesday_of_month
      - conditions:
          - condition: state
            entity_id: sensor.last_wednesday_of_month
            state: "5"
        sequence:
          - service: notify.mobile_app_pixel_6_pro
            data:
              message: The last Wednesday of the month is coming up in 5 days!

[Tarusky80]

Perfect!
It didn’t give me the “LAST” option because I hadn’t rebooted…lol

I had another idea.
Could it be possible to indicate the remaining time from the last MONDAY and TUESDAY taking into count the last Wednesday?
For example, in July, the month ends on Monday 31st, so since there is no following Tuesday and Wednesday, the count should start from 26th July.

I work out of office on the last MONDAY, TUESDAY and WEDNESDAY of the month, but if the month ends earlier and I don’t have a TUESDAY and WEDNESDAY, I have to bring everything forward to the previous week.

Maybe I’m asking too much, just in case forget it.

[ben.mcclure]

No problem! I’d be happy to help make sure it can work for your use case if I can.

Currently, you can use the “last” week in two ways:

1. The last Wednesday of the month, which for July would be the 26th
2. The Wednesday of the last week of the month, which for July would actually be August 2nd

The part I’m not grasping yet is how the Monday and Tuesday should be taken into account, so I’m hoping you might be able to expand a bit on the desired behavior with additional examples.

Questions I’ve got:

1. If the last day of the month is Monday, then the chore should happen on the previous Wednesday and your 3 office days would be the previous Mon, Tue, and Wed, is that correct?
2. What if the last day of the month is Tuesday? Currently, this would cause the same result as the previous example, and the chore would be due on the previous Wednesday (thus the assumption is all your office days would be in the previous week again)

[Tarusky80]

The month of May ends on the 31st, and has MONDAY 29, TUESDAY 30 and WEDNESDAY 31 as its last days.
So I have my appointments on the last WEDNESDAY,
the last TUESDAY and the last MONDAY of the month in the correct position.

The month of June ends on the 30th, so I have the 26th, 27th and 28th in correct position.

The month of July, on the other hand, ends on MONDAY, and I don’t have a subsequent TUESDAY and WEDNESDAY to exploit before the end of the month, so I have to ANTICIPATE everything to the 26th, 25th and 24th.

While now, in the Home assistant calendar, it marks me (in JULY) on the 31st, 24th and 25th.
While (for me) 24, 25 and 26 July would be fine.

current situation:

as (in my case) it should be:

---

Another IDEA, it would be nice to integrate with public holidays, using WORKDAY Workday - Home Assistant
to decide whether to take public holidays into account.

Sorry for my English, but I’m using a translator.

[ben.mcclure]

If you base the chore on the last wednesday of the month, and extrapolate the other two days from that, then they should always follow the schedule you want. But, it would be convenient to have 3 chores in your case I would think, one for each day, so that they show up on the calendar.

I think you could solve this currently with the following setup:

• 1 chore scheduled for the last Wednesday of every month
• 2 chores with a manual schedule to represent Monday and Tuesday
• An automation similar to my previous example that auto-completes the Wednesday chore after the due date
• An automation that runs when the due date of the Wednesday chore changes, and sets the due date of the Monday and Tuesday chores based on an offset from the new Wednesday due date.

That would be the simple way to do it, and it would mean your 3 days for the upcoming month would always be scheduled. The only downside is future months would only show Wednesday on the calendar until the previous month’s dates have passed, since there’s no due date forecasting with manual chores currently.

There is also potentially a way around that if you’re willing to dig deeper. Chore Helper fires a chore_helper_loaded event when it calculates all the due dates for a chore, and it contains a dictionary with the keys entity_id and due_dates (a list of dates). So that last automation I mentioned above could listen for chore_helper_loaded, test for the entity ID of the wednesday chore, and do something with the list of due dates. But it seems like looping through those dates and calling a service on each one within the automation might be the tricky part.

Alternately, I could add a feature where monthly chores can have a due date offset, so you could schedule all 3 chores for the last Wednesday of the month, but the actual due dates would be offset by -2, -1, and 0 respectively. I could definitely see the use case for this, although it might be a bit of a niche use case. But it would make that particular use case much easier to manage.

I’d be curious to hear your thoughts on the potential solutions

[ben.mcclure]

Thinking this through a little further, there may be another option too:

• 3 chores, all scheduled for the last Wednesday, but named for Monday, Tuesday, and Wednesday
• An automation that auto-completes each chore when it hits -1
• An automation that runs when the due date is set for the Tuesday chore and calls the Chore: offset_date service with the current due date and an offset of -1
• A similar automation for the Monday chore with an offset of -2

It does still carry the downside that all 3 chores would be due on Wednesday if you’re forecasting future due dates. But if you only care about the upcoming month, then that could work well.

Really I guess it’s no cleaner than having the Monday and Tuesday chores be manual like the previous option, since the future dates wouldn’t be accurate past the upcoming month anyway.

I could still see a possible use case for having an offset baked into the schedule though. I don’t know how useful it would be, but you could, for instance, schedule chores during the last FULL week in a month, regardless of which day you actually want to do the chore. So maybe that’s a feature that I should add, or at least consider.

[ben.mcclure]

I decided that a configuration option for a monthly due date offset is simple to add and unobtrusive enough for those who don’t need to use it. So, I implemented it in the main branch!

Version 0.4 is out now containing this enhancement!

Now, you can simply create 3 chores:

• 1 chore scheduled on the last wednesday of every month
• 1 chore scheduled on the last wednesday of every month with a due date offset of -1
• 1 chore scheduled on the last wednesday of every month with a due date offset of -2

All 3 chores should then always fall on the last week of the month containing a Wednesday.

[ASNNetworks]

You know what would be very cool? If this took the same approach of scheduler integration. That’s an awesome scheduler component that also has its own card, which allows the user to create new schedules, edit them and manage them straight from lovelace.

Chore helper would be amazing if it took the same approach with its own card, so you can create, edit and delete chores straight from lovelace through its card.

[ben.mcclure]

Thanks for the comment! Scheduler is really cool and powerful, and being able to manage schedules on the front-end is awesome. That is a great idea for Chore Helper!

I plan on creating a Chore Helper Card repo soon which at the very least makes it simple to filter chores and adds options for each one to complete it, skip it, offset it, etc.

The ability to schedule a new chore, or delete an existing one, from the front-end card would be interesting, too, that’s a great idea, and it seems like we should be able to use the Scheduler Card and particularly the scheduler-card-editor implementation as a reference for how to do this.

I’ll be starting on the card repo soon, but it might be a while until I have a full front-end editor in place.

[ASNNetworks]

Good to know! I’ll gladly help if you need any beta testing done. I’ll keep an eye on this thread, but feel free to tag or message me when you need a tester !

[ben.mcclure]

That’s great to hear, thank you for offering to help test! I’ll tag you when that’s ready for further testing

[Tarusky80]

@ben.mcclure

I decided that a configuration option for a monthly due date offset is simple to add and unobtrusive enough for those who don’t need to use it. So, I implemented it in the main branch!

Version 0.4 is out now containing this enhancement!

Now, you can simply create 3 chores:

• 1 chore scheduled on the last wednesday of every month
• 1 chore scheduled on the last wednesday of every month with a due date offset of -1
• 1 chore scheduled on the last wednesday of every month with a due date offset of -2

All 3 chores should then always fall on the last week of the month containing a Wednesday.

Gorgeous!
I try it later.

It’s becoming perfect

[Tarusky80]

Integration with WORKDAY or any other sensor that considers important dates would be the TOP

[ben.mcclure]

That sounds nice, but I think the challenge is that there are many possible variations of what someone might want to do with a chore based on a workday or holiday condition, and potentially multiple sensors that someone would want to take into account. I’m not opposed to directly supporting something like that, but would need to figure out what the user experience should be for configuring it. Do you envision it working a certain way?

You could also use an automation to offset chore dates based on any conditions, but it would be ideal to be able to offset the chore date ahead of time, whereas a binary sensor that only measures the current state wouldn’t be able to offset the chore until the day that the sensor flips to on.

[Tarusky80]

Sure, of course
However for now it works very well, I am very satisfied.
Compliments