Sensor Reference

TaskMate creates the following entities in Home Assistant.

Architecture note: The overview sensor's attributes have been split across companion sensors (sensor.taskmate_chores, sensor.taskmate_rewards, etc.) to stay under the 16KB recorder limit. Cards use the __taskmate_attrs helper to transparently merge data from all sensors.

---

sensor.taskmate_overview

The main overview sensor. Carries scalar stats and the compact per-child summary.

Property	Value
State	Number of children
Icon	mdi:clipboard-check-multiple

Top-Level Attributes

Attribute	Type	Description
total_children	int	Number of children
total_chores	int	Number of defined chores
total_rewards	int	Number of defined rewards
total_points_available	int	Sum of all children's current points
total_chores_completed	int	Sum of all-time chore completions across all children
total_completions_all_time	int	Lifetime chore completion records
total_pending_completions	int	Chore completions awaiting approval
points_name	string	Currency name (e.g. "Stars")
points_icon	string	Currency MDI icon (e.g. "mdi:star")
card_design	string	Global default card design style — classic / playroom / console / cleanpro (default classic). Cards apply this when they have no per-card override. See Card Design Styles
today_day_of_week	string	Current day in HA timezone (e.g. "monday")
weekend_multiplier	float	Current weekend multiplier setting
streak_reset_mode	string	"reset" or "pause"
streak_milestones_enabled	bool	Whether streak milestone bonuses are on
streak_milestones	string	Current milestone configuration string
perfect_week_enabled	bool	Whether perfect week bonus is on
perfect_week_bonus	int	Perfect week bonus points value
time_boundaries	dict	Legacy fixed time-window map: morning_start/morning_end/afternoon_start/… in HH:MM (kept for cards that read the four fixed periods)
time_periods	list	Custom time-of-day periods — each entry has id, label, start, end, icon. Drives chore time-category windows
vacation_active	bool	true if a vacation period covers today
vacation_name	string	Name of the active vacation period (empty when none)
vacation_end	string	ISO end date of the active vacation period (empty when none)
vacation_periods	list	All configured vacation periods — each has id, name, start, end. See Vacation Mode

Note: Level/XP, quest, challenge, and avatar-unlock data are carried per child inside the children array (see below), not as top-level attributes. See Levels and XP, Quests, Challenges, Avatars.

children Array

Each entry in the children array:

Field	Type	Description
id	string	Child's unique ID
name	string	Child's display name
avatar	string	MDI icon (the child's currently selected avatar)
level	int	Current XP level (derived from total_points_earned). See Levels and XP
level_progress	int	XP earned toward the next level within the current level band
level_target	int	XP required per level (the level_xp_step setting; default 100)
points	int	Current gross points balance (after pool deposits deducted)
pending_points	int	Points held by pending chore approvals
committed_points	int	Points reserved by pending reward claims
spendable_balance	int	points − committed_points — what the child can spend or deposit now
allocated_points	int	Total points deposited across all reward pools
total_points_earned	int	All-time points earned
total_chores_completed	int	All-time completions
current_streak	int	Current consecutive day streak
best_streak	int	Best streak ever
pending_points	int	Points held by pending approvals
committed_points	int	Points reserved by pending reward claims
chore_order	list	Custom chore display order
last_completion_date	string	ISO date of last completion
streak_paused	bool	Whether streak is paused
streak_milestones_achieved	list	Milestone day counts already awarded this streak
awarded_perfect_weeks	list	Monday ISO dates of awarded perfect weeks
career_score	int	Long-term score (total_points_earned − total_penalties_received)
total_penalties_received	int	Lifetime count of penalties applied
quests	list	This child's quest progress — each entry has quest_id, name, icon, total_steps, step, done, times_completed, bonus_points, next_chore_id
challenges	list	This child's challenge progress — each entry has challenge_id, name, icon, scope, metric, target, progress, value, bonus_points, complete, awarded
avatar_options	list	The avatar catalogue resolved for this child — each entry has id, label, icon, unlocked, requirement (human-readable unlock condition)

quests entry fields:

Field	Type	Description
quest_id	string	Quest ID
name	string	Quest display name
icon	string	MDI icon
total_steps	int	Number of chore steps in the chain
step	int	Child's current step (0-indexed, capped at total_steps)
done	bool	true when step >= total_steps
times_completed	int	How many times this child has completed the chain
bonus_points	int	Points awarded on completing the final step
next_chore_id	string	Chore ID of the next step to complete (empty when done)

challenges entry fields:

Field	Type	Description
challenge_id	string	Challenge ID
name	string	Challenge display name
icon	string	MDI icon
scope	string	daily or weekly (week starts Monday)
metric	string	chores (count of completions) or points (points earned)
target	int	Goal value for the metric this period
progress	int	Progress toward target, capped at target
value	int	Actual current value (may exceed target)
bonus_points	int	Points awarded once the target is hit
complete	bool	true when value >= target
awarded	bool	true when the bonus has already been credited this period

avatar_options entry fields:

Field	Type	Description
id	string	Avatar catalogue ID
label	string	Display name
icon	string	MDI icon
unlocked	bool	Whether this child meets the unlock condition
requirement	string	Human-readable unlock condition — "" (free), "Level X", "X earned", or "X-day streak"

Note: The following arrays (chores, rewards, todays_completions, recent_completions, recent_transactions, pending_completions, pending_reward_claims) are served by companion sensors (see below). Cards merge them transparently via the __taskmate_attrs helper.

chores Array

Each entry in the chores array (from sensor.taskmate_chores):

Field	Type	Description
id	string	Chore's unique ID
name	string	Display name
description	string	Optional description (omitted when empty)
points	int	Base points (before multipliers) awarded on completion
difficulty	string	easy / medium / hard — only emitted when not medium. See Difficulty Tiers
effective_points	int	Points actually awarded after the difficulty multiplier — only emitted when it differs from points
mandatory	bool	true for a mandatory chore — only emitted when set (so cards can show the mandatory badge/styling)
mandatory_penalty_points	int	Penalty deducted if the chore is missed — only emitted when mandatory is set and the penalty is non-zero. See Mandatory Chores
require_photo	bool	true when the chore requires a photo proof — only emitted when set
time_category	string	morning / afternoon / evening / night / anytime
schedule_mode	string	specific_days / recurring / one_shot
daily_limit	int	Max completions per day (omitted when 1)
claim_allowance_minutes	int	Grace minutes past the period end during which the chore stays claimable (omitted when 0)
assigned_to	list	List of child IDs (empty = all children)
completion_sound	string	Sound name (omitted when default coin)
due_days	list	Scheduled days for specific_days mode (omitted when empty)
recurrence	string	every_2_days / weekly / every_2_weeks / monthly / every_3_months / every_6_months (omitted when weekly)
recurrence_day	string	Day-of-week anchor for recurring weekly/fortnightly (omitted when empty)
recurrence_start	string	ISO date anchor for every_2_days recurrence (omitted when empty)
visibility_entity / visibility_operator / visibility_state	string	Dynamic visibility guard — emitted together when visibility_entity is set. See Dynamic Chore Visibility
requires_approval	bool	Whether parent approval is needed (omitted when true — default)
assignment_mode	string	everyone / alternating / random / balanced / first_come / unassigned. See Chore Scheduling
assignment_current_child_id	string	Child ID assigned today (for alternating/random/balanced modes; omitted when empty)
enabled	bool	Whether the chore is active (false for soft-disabled one-shot chores)
disabled_for	list	Child IDs for whom this chore is individually disabled
created_date	string	ISO date for one-shot chore expiry (e.g. "2026-04-16")
task_type	string	standard or timed
timed_rate_points	int	Points per rate window (timed chores only)
timed_rate_minutes	int	Rate window in minutes (timed chores only)
timed_max_daily_minutes	int	Daily cap in minutes; 0 = unlimited (timed chores only)
bonus_subtasks	list	Embedded bonus subtasks — each has id, name, points (description is omitted from the sensor payload)

Compact payloads: The chores sensor deliberately omits rarely-used fields to stay under the 16KB recorder limit. publish_calendar_entities, last_completed_at, first_occurrence_mode, assignment_rotation_anchor, and the per-child availability matrix are not in this list. Per-child availability lives on sensor.taskmate_chore_availability. The chore editor fields expires_on, due_time / early_bonus / late_penalty, and require_availability are stored on the chore but are not emitted on this sensor; manage them in the Admin Panel.

rewards Array

Each entry in the rewards array:

Field	Type	Description
id	string	Reward's unique ID
name	string	Display name
description	string	Optional description
cost	int	Fixed point cost set by the parent
icon	string	MDI icon
assigned_to	list	Child IDs (empty = all children)
is_jackpot	bool	Whether this is a pooled jackpot reward
pool_enabled	bool	Whether this reward uses savings-jar (pool) semantics
calculated_costs	dict	Per-child cost {child_id: cost}
pool_allocations	dict	Per-child pool deposits {child_id: points}
jackpot_pool_total	int|null	Combined pool total for jackpot rewards; null otherwise
quantity	int|null	Remaining stock (null = unlimited)
expires_at	string|null	ISO date expiry deadline (null = never)
is_sold_out	bool	true when quantity has reached 0
is_expired	bool	true when past the expiry date
is_available	bool	true when not sold out and not expired
days_until_expiry	int|null	Days remaining until expiry (null if no expiry set)

Note: Auto-restock fields (restock_enabled, restock_amount, restock_period, restock_last) are stored on the reward but are not emitted on the sensor — they drive the periodic stock reset only. The reward-level spending cap is a global setting, not a per-reward field. See Points Economy and Rewards.

todays_completions Array

Completions from today (both approved and pending):

Field	Type	Description
completion_id	string	Unique completion ID
chore_id	string	Chore ID
child_id	string	Child ID
child_name	string	Child display name
chore_name	string	Chore display name
points	int	Points value
approved	bool	Whether approved
completed_at	string	ISO datetime

recent_completions Array

Up to 35 most recent completions across all time (capped to stay under the 16KB recorder limit).

Same fields as todays_completions.

pending_completions Array

Unapproved chore completions waiting for parent action:

Field	Type	Description
completion_id	string	Unique completion ID
chore_id	string	Chore ID
child_id	string	Child ID
child_name	string	Child display name
chore_name	string	Chore display name
points	int	Points value
time_category	string	Time of day
completed_at	string	ISO datetime

pending_reward_claims Array

Unapproved reward claims waiting for parent action:

Field	Type	Description
claim_id	string	Unique claim ID
reward_id	string	Reward ID
child_id	string	Child ID
child_name	string	Child display name
reward_name	string	Reward display name
cost	int	Points cost at time of claim
claimed_at	string	ISO datetime

recent_transactions Array

Up to 20 most recent points transactions and reward claim events:

Field	Type	Description
id	string	Transaction ID
child_id	string	Child ID
points	int	Points value (positive = add, negative = remove)
reason	string	Reason description
created_at	string	ISO datetime

active_timed_sessions Array

Active or paused timed task sessions:

Field	Type	Description
chore_id	string	Chore ID
child_id	string	Child ID
state	string	running or paused
total_seconds_today	int	Cumulative elapsed seconds today
current_segment_start	string|null	ISO datetime of current running segment start

---

sensor.pending_approvals

Numeric count of total pending items.

Property	Value
State	Integer — total pending items
State class	measurement
Icon	mdi:clipboard-clock

Attributes

Attribute	Type	Description
pending_chore_completions	int	Count of chores awaiting approval
pending_reward_claims	int	Count of reward claims awaiting approval
pending_mandatory_misses	int	Count of unresolved mandatory-miss review items
chore_completions	list	Full details of pending chore completions
reward_claims	list	Full details of pending reward claims
mandatory_misses	list	Unresolved mandatory-miss review items (see below). See Mandatory Chores

chore_completions entries:

Field	Description
completion_id	Completion ID (use with approve_chore / reject_chore)
type	Always "chore"
child_name	Child display name
child_id	Child ID
chore_name	Chore display name
chore_id	Chore ID
points	Points value
time_category	Time of day
completed_at	ISO datetime

reward_claims entries:

Field	Description
claim_id	Claim ID (use with approve_reward / reject_reward)
type	Always "reward"
child_name	Child display name
child_id	Child ID
reward_name	Reward display name
reward_id	Reward ID
cost	Points cost
claimed_at	ISO datetime

mandatory_misses entries:

A pending mandatory chore miss, one per chore/child/day. Resolve with apply_mandatory_penalty, postpone_mandatory_chore, or dismiss_mandatory_chore (see Services).

Field	Description
id	Miss ID (use with the mandatory-miss services as miss_id)
chore_id	Chore ID
child_id	Child ID
chore_name	Chore display name
child_name	Child display name
due_date	ISO date the chore was missed
period_id	The time-of-day period whose window closed (anytime for an all-day chore)
penalty_points	Penalty snapshotted at miss time (applied by apply_mandatory_penalty)
postpone_count	How many times this miss has been postponed
created_at	ISO datetime the miss was recorded

---

sensor.taskmate_chores

Chore definitions and today's completions.

Property	Value
State	Number of defined chores
Icon	mdi:format-list-checks

Attributes

Attribute	Type	Description
chores	list	Full chore definitions (see chores array above)
todays_completions	list	Completions logged today (see todays_completions array above)
task_groups	list	Task group definitions — each has id, name, policy, chore_ids. See Task Groups
active_timed_sessions	list	Running/paused timed sessions (see active_timed_sessions array below)
vacation_active	bool	true if a vacation period covers today
vacation_name	string	Name of the active vacation period (empty when none)
vacation_end	string	ISO end date of the active vacation period (empty when none)

---

sensor.taskmate_chore_availability

Per-chore per-child availability matrix. Split from the chores sensor to keep payloads compact.

Property	Value
State	Count of available chore/child combinations
Icon	mdi:calendar-check

Attributes

Attribute	Type	Description
chore_availability	dict	{chore_id: {child_id: bool}} — whether each chore is available for each child today

---

sensor.taskmate_rewards

Rewards catalogue, pending claims, and pool allocations.

Property	Value
State	Number of defined rewards
Icon	mdi:gift-outline

Attributes

Attribute	Type	Description
rewards	list	Full reward definitions (see rewards array above)
pending_reward_claims	list	Pending reward claims (see pending_reward_claims array above)
pool_allocations	list	Raw pool allocation records

---

sensor.taskmate_activity

Recent completion and transaction history.

Property	Value
State	Total number of all-time completions
Icon	mdi:history

Attributes

Attribute	Type	Description
recent_completions	list	Up to 35 most recent completions (see recent_completions array above)
recent_transactions	list	Up to 20 most recent point adjustments and reward events (see recent_transactions array above)
career_score_history	dict	{child_id: [...]} — recorded career-score snapshots per child, for trend charts

---

sensor.taskmate_incentives

Penalties and bonuses catalogue.

Property	Value
State	Total number of penalties + bonuses
Icon	mdi:scale-balance

Attributes

Attribute	Type	Description
penalties	list	Penalty definitions — each has id, name, points, description, icon, assigned_to
bonuses	list	Bonus definitions — each has id, name, points, description, icon, assigned_to

Note: task_groups is published on sensor.taskmate_chores, not on the incentives sensor.

---

Per-Child Sensors

Each child gets two sensors:

sensor.{child_name}_points — State: current gross points balance. State class: total.

Attribute	Type	Description
child_id	string	Child ID
child_name	string	Display name
avatar	string	MDI icon
total_points_earned	int	Lifetime points earned
total_chores_completed	int	Lifetime completions
current_streak	int	Current consecutive day streak
best_streak	int	Best streak ever
career_score	int	Long-term score (total_points_earned − total_penalties_received)

sensor.{child_name}_stats — State: total chores completed. State class: total.

Attribute	Type	Description
child_id	string	Child ID
child_name	string	Display name
avatar	string	MDI icon
points	int	Current points balance
total_points_earned	int	Lifetime points earned
total_chores_completed	int	Lifetime completions
current_streak	int	Current streak
best_streak	int	Best streak
career_score	int	Long-term score
total_penalties_received	int	Lifetime penalties applied
assigned_chores	list	Chores assigned to this child today (each has id, name, points, time_category)
chore_order	list	Custom chore display order

---

Per-Child Badge Sensors

sensor.taskmate_badges_{child_slug} — State: count of earned badges.

Attribute	Type	Description
earned	list	Array of earned badge objects, each with badge_id, name, icon, tier, earned_at, manually_awarded (bool), silent (bool)
available	list	Array of not-yet-earned applicable badges, each with badge_id, name, icon, tier, progress_pct, criteria_summary
total_badges	int	Number of badges applicable to this child (earned + locked)

See Achievement Badges for full details.

---

binary_sensor.taskmate_has_pending_approvals

Simple on/off sensor for use in automations and notifications.

Property	Value
on	There are pending chore completions or reward claims
off	Nothing pending
Icon (on)	mdi:bell-alert
Icon (off)	mdi:bell-check
Device class	None

Attributes

Attribute	Type	Description
pending_chore_completions	int	Count of chores pending
pending_reward_claims	int	Count of reward claims pending
total_pending	int	Combined total

---

Button Entities

One button entity per child/chore combination and per child/reward combination:

Entity	Action
button.{child}_complete_{chore}	Complete the chore for the child
button.{child}_claim_{reward}	Claim the reward for the child

The reward claim button is only available (not greyed out) when the child has enough points.

---

Calendar Entities (v4.2.0)

One read-only calendar entity per child, created by the calendar platform and added automatically as children are created:

Entity	Description
calendar.taskmate_<child>	Friendly name TaskMate <child> (icon mdi:calendar-account). Projects the child's upcoming chore occurrences from the recurrence/assignment engine — timed events inside the chore's time-of-day window, or all-day events for anytime chores. Away periods appear as coalesced multi-day "Away" all-day events (chores are hidden on away days). The entity state is the current or next upcoming event.

Read-only — completing a chore from the calendar is not supported. See Calendar.

---

Admin-Panel-Only Data (not entity attributes)

Some v4.0.0 data is served to the Admin Panel over the websocket API rather than exposed as sensor attributes:

Data	Where	Notes
Quest definitions	websocket state quests / quest_progress	Per-child quest progress is mirrored into the overview children[].quests. See Quests
Challenge definitions	websocket state challenges	Per-child progress is mirrored into children[].challenges. See Challenges
Avatar catalogue	websocket state avatar_catalog	Per-child unlock state is mirrored into children[].avatar_options. See Avatars
Swap requests	websocket state swap_requests	Pending chore swap requests awaiting parent action
Audit log	websocket commands taskmate/audit/list + /clear; initial state audit_log (newest 100)	See Admin Audit Log

---

Sensor Update Frequency

The coordinator polls every 30 seconds. All entities update together. Completions, approvals, and point changes trigger an immediate refresh.