Choremander

Turn chores into a game your kids actually want to play.
A Home Assistant integration for family chore management with smart rewards.

Why Choremander?

Kids don't naturally love chores. But they do love games, progress bars, and earning things. Choremander turns daily responsibilities into a reward system that actually motivates.

Build Better Habits Through Gamification

Visual progress toward goals keeps kids engaged
Immediate feedback (points, sounds, celebrations) reinforces positive behavior
Clear expectations - kids know exactly what's required and what they'll earn

Encourage the Right Behaviors

Not all chores are equal. Some are easy (brush teeth), others take effort (homework, practice). With Choremander:

Weight points by difficulty - Give 1 star for easy tasks, 5 stars for harder ones
Harder chores = faster rewards - Kids learn that putting in effort pays off
No gaming the system - Smart pricing means you can't just spam easy chores to win

Flexible Rewards That Make Sense

Per-child or shared - Define rewards for one kid or assign to multiple
Smart pricing per child - Even shared rewards calculate costs individually based on each child's chores and completion rates
Control the pace - Set how many days a reward should take to earn; the system calculates the rest
Jackpot rewards - Pool stars from all kids toward big family goals (vacation, museum trip, etc.)

Quick Start

Install via HACS

HACS → Integrations → ⋮ menu → Custom repositories
Add https://github.com/vinnybad/choremander as an Integration
Search "Choremander" and install
Restart Home Assistant

Configure

Settings → Devices & Services → Add Integration → "Choremander"
Choose your points currency (Stars, Coins, Bucks, etc.)
Click Configure on the integration to manage everything:

Features

Chores

Feature	Description
Points	Stars earned for completion
Time of Day	Morning, Afternoon, Evening, Night, or Anytime
Completion % Per Month	Expected completion rate (100 = daily, 50 = every other day) - used for smart reward pricing
Daily Limit	How many times per day the chore can be completed
Requires Approval	Parent must approve before points are awarded

Rewards

Type	Description
Dynamic (default)	Cost auto-calculated: `Days to Goal` × expected daily earnings (based on each chore's points and completion rate)
Fixed	Toggle "Override Point Value" to set a manual cost
Jackpot	Pool stars from ALL assigned children toward one big family reward

Dashboard Cards

Cards auto-register when the integration loads. Just add them to your Lovelace dashboard - no manual resource configuration needed!

Adding Cards (Visual Editor)

The easiest way to add Choremander cards:

Edit your dashboard and click Add Card
Search for the card (e.g., "choremander-child-card") or scroll to find it under "Custom"
Alternatively, add a Manual card and enter the card type (e.g., custom:choremander-child-card)
The card will show a configuration interface - enter sensor.choremander_overview in the entity field
Fill in any additional options (child selection, time of day, etc.) and save

Tip: If the card shows an error after adding, click on it to open the configuration panel. This is normal - it just needs to be configured!

YAML Mode Users

If you use Lovelace in YAML mode, add these resources to your configuration.yaml:

lovelace:
  resources:
    - url: /choremander/choremander-child-card.js
      type: module
    - url: /choremander/choremander-rewards-card.js
      type: module
    - url: /choremander/choremander-approvals-card.js
      type: module
    - url: /choremander/choremander-points-card.js
      type: module
    - url: /choremander/choremander-reorder-card.js
      type: module

Card Index

Card	For	Description
Child Card	Kids	Kid-friendly chore completion interface
Rewards Card	Kids	View available rewards and progress
Approvals Card	Parents	Approve or reject completed chores
Points Card	Parents	Manually add/remove points
Reorder Card	Parents	Organize chore display order per child

Tip: Create separate dashboards - one for kids (Child + Rewards) and one for parents (Approvals + Points).

Cards for Kids

Child Card

Kid-friendly interface with big colorful buttons and celebration sounds. This is the primary way children interact with their chores.

Visual Editor: Add custom:choremander-child-card, then configure the entity (sensor.choremander_overview), select a child, and optionally filter by time of day.

YAML Example

type: custom:choremander-child-card
entity: sensor.choremander_overview
child_id: a8c8376a
time_category: morning  # Optional: morning, afternoon, evening, night, anytime
title: My Chores        # Optional
density: compact        # Optional: default, cozy, compact
show_header: false      # Optional: hide the avatar / name / balance strip

The same card at each density — the chores and the child are identical, only the option differs:

What that adds up to on a phone. Same dashboard, one screen:

Layout options

Option	Values	Default	What it does
`density`	`default`, `cozy`, `compact`	`default`	How much space each chore takes. `compact` fits roughly twice as many chores on a phone screen.
`show_header`	bool	`true`	The avatar, name and star balance across the top. Turn off if you show the balance elsewhere.
`show_avatar`	bool	`true`	Just the round avatar.
`show_title`	bool	`true`	The "Morning Chores" heading.
`show_numbers`	bool	`true`	The coloured number badge on each chore.
`show_chore_points`	bool	`true`	The star value under each chore name.
`animations`	bool	`true`	The floating avatar and spinning stars. Celebrations still play.

Tap targets do not shrink with density: a chore row stays at least 56px tall and the checkbox at least 40px at every setting, because the whole row is the button and it is a small child doing the tapping. The card also honours your operating system's "reduce motion" setting on its own.

Rewards Card

Shows all available rewards with progress bars. Displays dynamic pricing indicators and jackpot status.

Visual Editor: Add custom:choremander-rewards-card, configure the entity, and optionally filter to a specific child.

YAML Example

type: custom:choremander-rewards-card
entity: sensor.choremander_overview
child_id: 6ddfca70  # Optional: filter to specific child
density: compact    # Optional: default, cozy, compact
animations: false   # Optional: stop the shimmer and jackpot shine

Cards for Parents

Approvals Card

Review and approve (or reject) completed chores that require parent approval. Shows pending items grouped by time of day.

Visual Editor: Add custom:choremander-approvals-card and configure the entity.

YAML Example

type: custom:choremander-approvals-card
entity: sensor.choremander_overview

Points Card

Manually add bonus points (great job today!) or remove points (consequences). Useful for situations outside the normal chore flow.

Visual Editor: Add custom:choremander-points-card and configure the entity.

YAML Example

type: custom:choremander-points-card
entity: sensor.choremander_overview

Reorder Card

Drag-and-drop interface to organize the order chores appear for each child. Customize the experience per kid.

Visual Editor: Add custom:choremander-reorder-card, configure the entity, and select a child.

YAML Example

type: custom:choremander-reorder-card
entity: sensor.choremander_overview
child_id: a8c8376a

Note: All cards require the sensor.choremander_overview entity. Child-specific cards also need a child selection.

Custom Styling

If density does not get you where you want, the Child Card and Rewards Card expose every size as a CSS custom property. Set one anywhere above the card - a Home Assistant theme, or a card_mod block on a single card - and it wins over the built-in value.

# In your theme, applying to every Choremander card at once
my_theme:
  chm-chore-min-height: 48px
  chm-chore-name-font-size: 1rem
  chm-card-background: "linear-gradient(135deg, #11998e 0%, #38ef7d 100%)"

# Or with card_mod, on one card only
type: custom:choremander-child-card
entity: sensor.choremander_overview
child_id: a8c8376a
card_mod:
  style: |
    :host {
      --chm-chore-radius: 4px;
      --chm-color-purple: #e91e63;
    }

Child Card properties

Property	Default
`--chm-card-background`	`linear-gradient(135deg, #667eea 0%, #764ba2 100%)`
`--chm-card-radius`	`24px`
`--chm-header-padding`	`20px 24px`
`--chm-avatar-size` / `--chm-avatar-icon-size`	`70px` / `50px`
`--chm-name-font-size`	`clamp(1.2rem, 5vw, 2rem)`
`--chm-balance-padding` / `--chm-balance-radius`	`12px 16px` / `20px`
`--chm-chores-padding` / `--chm-chores-gap` / `--chm-chores-min-height`	`24px` / `20px` / `200px`
`--chm-title-font-size` / `--chm-title-icon-size`	`1.8rem` / `36px`
`--chm-chore-padding` / `--chm-chore-min-height`	`20px 24px` / `80px`
`--chm-chore-radius` / `--chm-chore-border-width`	`24px` / `4px`
`--chm-chore-name-font-size` / `--chm-chore-points-font-size`	`1.5rem` / `1.2rem`
`--chm-badge-size` / `--chm-badge-font-size`	`42px` / `1.5rem`
`--chm-checkbox-size` / `--chm-checkbox-icon-size`	`44px` / `28px`
`--chm-color-pink`, `-purple`, `-blue`, `-green`, `-yellow`, `-orange`, `-red`, `-cyan`	the built-in palette

Rewards Card properties

Property	Default
`--chm-header-padding` / `--chm-header-title-font-size`	`16px 20px` / `1.3rem`
`--chm-content-padding` / `--chm-content-gap`	`16px` / `12px`
`--chm-reward-padding` / `--chm-reward-gap` / `--chm-reward-radius`	`16px` / `16px` / `12px`
`--chm-cost-badge-min-width` / `--chm-cost-badge-padding`	`70px` / `12px 8px`
`--chm-cost-value-font-size` / `--chm-cost-label-font-size`	`1.4rem` / `0.65rem`
`--chm-reward-name-font-size` / `--chm-reward-desc-font-size`	`1.15rem` / `0.9rem`
`--chm-progress-height` / `--chm-jackpot-progress-height`	`14px` / `18px`
`--chm-reward-icon-size` / `--chm-reward-icon-glyph-size`	`44px` / `24px`

If you set both, the density option wins - it is the more specific instruction. To restyle a card that also uses a density, target :host([density="compact"]) in your card_mod block.

Smart Reward Pricing

The goal: every reward should take a predictable amount of time to earn - not random guessing.

The Problem with Fixed Prices

If you set "Family Movie Night" to cost 500 stars, how long does that take? A week? A month? You'd have to manually calculate based on all assigned chores... and recalculate every time you add or change one.

How Smart Pricing Works

You set Days to Goal (e.g., 14 days). Choremander does the math:

Looks at each chore's point value and expected completion rate
Calculates how many points the child should earn per day
Sets the reward cost so it takes exactly that many days

Daily Expected Points = Sum of (Chore Points × Completion %)
Reward Cost = Daily Expected Points × Days to Goal

Why This Encourages Better Behavior

Here's the key insight: completion rate matters.

If a child only does "Homework" 60% of the time but "Brush teeth" 100% of the time, the pricing reflects that. Kids who consistently do the harder chores will hit their goals faster than kids who only do the easy ones.

The incentive: Want that reward sooner? Do the challenging stuff, not just the minimum.

Behavior	Result
Only does easy daily chores	Earns rewards at the expected pace
Tackles harder/optional chores	Earns rewards faster than expected
Skips difficult chores	Falls behind the expected pace

Jackpot Rewards

For big family goals (vacation, museum trip), enable Jackpot mode. All children's stars pool together toward one shared reward - teamwork!

Tips

Two dashboards: One for kids (Child + Rewards), one for parents (Approvals + Points)
Completion %: Set lower for optional/weekly chores so they don't inflate reward costs
All data is local: Nothing leaves your Home Assistant instance

Development

Testing Changes Locally

A full local environment is included: a real Home Assistant in Docker with seeded family data, plus three test layers that run against it. Nothing touches your real Home Assistant instance.

See docs/TESTING.md for the complete guide.

Requirements

Docker and Docker Compose
Python 3.13 and Node 20+ (only if you want to run the test suites)

Quick Start

make install    # venv, Python deps, Node deps, Chromium
make up         # start Home Assistant and wait until Choremander loads
make verify     # lint + unit tests + API e2e + browser e2e

make up is fully non-interactive: it starts the container, completes onboarding over the REST API, creates the dev user, and blocks until the integration has actually loaded. Log in at http://localhost:8123 with dev / dev.

Three dashboards are pre-configured in the sidebar:

URL	Contents
`/krishna`	Kid dashboard — chores, progress, rewards
`/radha`	Kid dashboard
`/parent`	Approvals, points management, chore reorder

Development Workflow

# After changing Python files:
make restart          # restarts and waits until it is serving again

# After changing JS card files, just hard refresh the browser (Cmd+Shift+R)

make test             # fast unit tests, no container needed
make e2e              # API-driven tests against the live container
make browser          # Playwright tests driving the real cards
make browser-headed   # ...and watch them run

make logs             # follow filtered container logs
make shell            # shell inside the container
make seed             # restore the seeded family data
make reset            # wipe all generated state
make down             # stop

Run make help for the full list.

Pre-configured Test Data

The dev environment comes with:

2 kids: Krishna (25 stars) and Radha (15 stars)
8 chores:
- Shared: Make Bed, Brush Teeth (AM/PM), Tidy Room
- Krishna only: Feed the Dog, Do Homework
- Radha only: Water the Plants, Practice Piano
5 rewards:
- 30 Min Screen Time (dynamic pricing, 7 days) - shared
- New Video Game (50 stars, fixed) - Krishna only
- New Book (30 stars, fixed) - Radha only
- Family Movie Night (jackpot, 14 days) - shared
- Trip to the Zoo (jackpot, 30 days) - shared

_{License: MIT}

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
custom_components/choremander		custom_components/choremander
dev		dev
docs		docs
e2e		e2e
images		images
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
hacs.json		hacs.json
logo.svg		logo.svg
pyproject.toml		pyproject.toml
requirements-test.txt		requirements-test.txt

Folders and files

Latest commit

History

Repository files navigation

Choremander

Contents

Why Choremander?

Build Better Habits Through Gamification

Encourage the Right Behaviors

Flexible Rewards That Make Sense

Quick Start

Install via HACS

Configure

Features

Chores

Rewards

Dashboard Cards

Adding Cards (Visual Editor)

YAML Mode Users

Card Index

Cards for Kids

Child Card

Rewards Card

Cards for Parents

Approvals Card

Points Card

Reorder Card

Custom Styling

Smart Reward Pricing

The Problem with Fixed Prices

How Smart Pricing Works

Why This Encourages Better Behavior

Jackpot Rewards

Tips

Development

Testing Changes Locally

Requirements

Quick Start

Development Workflow

Pre-configured Test Data

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages