{"id":35725560,"url":"https://github.com/vinnybad/choremander","last_synced_at":"2026-01-13T20:39:18.960Z","repository":{"id":331387353,"uuid":"1125718989","full_name":"vinnybad/choremander","owner":"vinnybad","description":"Family chore management with smart rewards for Home Assistant","archived":false,"fork":false,"pushed_at":"2026-01-06T06:42:45.000Z","size":1257,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-07T09:45:30.624Z","etag":null,"topics":["chores","custom-integration","gamification","hacs","home-assistant","kids"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vinnybad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-31T08:18:17.000Z","updated_at":"2026-01-06T06:42:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vinnybad/choremander","commit_stats":null,"previous_names":["vinnybad/choremander"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/vinnybad/choremander","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinnybad%2Fchoremander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinnybad%2Fchoremander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinnybad%2Fchoremander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinnybad%2Fchoremander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vinnybad","download_url":"https://codeload.github.com/vinnybad/choremander/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinnybad%2Fchoremander/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399924,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chores","custom-integration","gamification","hacs","home-assistant","kids"],"created_at":"2026-01-06T08:13:33.964Z","updated_at":"2026-01-13T20:39:18.955Z","avatar_url":"https://github.com/vinnybad.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.svg\" alt=\"Choremander\" width=\"180\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eChoremander\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eTurn chores into a game your kids actually want to play.\u003c/strong\u003e\u003cbr\u003e\n  A Home Assistant integration for family chore management with smart rewards.\n\u003c/p\u003e\n\n---\n\n## Contents\n\n- [Why Choremander?](#why-choremander)\n- [Quick Start](#quick-start)\n- [Features](#features)\n- [Dashboard Cards](#dashboard-cards)\n- [Smart Reward Pricing](#smart-reward-pricing)\n- [Tips](#tips)\n- [Development](#development)\n\n---\n\n## Why Choremander?\n\nKids 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.\n\n### Build Better Habits Through Gamification\n\n- **Visual progress** toward goals keeps kids engaged\n- **Immediate feedback** (points, sounds, celebrations) reinforces positive behavior\n- **Clear expectations** - kids know exactly what's required and what they'll earn\n\n### Encourage the Right Behaviors\n\nNot all chores are equal. Some are easy (brush teeth), others take effort (homework, practice). With Choremander:\n\n- **Weight points by difficulty** - Give 1 star for easy tasks, 5 stars for harder ones\n- **Harder chores = faster rewards** - Kids learn that putting in effort pays off\n- **No gaming the system** - Smart pricing means you can't just spam easy chores to win\n\n### Flexible Rewards That Make Sense\n\n- **Per-child or shared** - Define rewards for one kid or assign to multiple\n- **Smart pricing per child** - Even shared rewards calculate costs individually based on each child's chores and completion rates\n- **Control the pace** - Set how many days a reward should take to earn; the system calculates the rest\n- **Jackpot rewards** - Pool stars from all kids toward big family goals (vacation, museum trip, etc.)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/rewardsCard.png\" alt=\"Rewards Card\" width=\"350\"\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n### Install via HACS\n\n1. **HACS** → Integrations → ⋮ menu → **Custom repositories**\n2. Add `https://github.com/vinnybad/choremander` as an **Integration**\n3. Search \"Choremander\" and install\n4. **Restart Home Assistant**\n\n### Configure\n\n1. **Settings** → Devices \u0026 Services → **Add Integration** → \"Choremander\"\n2. Choose your points currency (Stars, Coins, Bucks, etc.)\n3. Click **Configure** on the integration to manage everything:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/settings.png\" alt=\"Settings Menu\" width=\"500\"\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\n### Chores\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/editChore.png\" alt=\"Edit Chore\" width=\"400\"\u003e\n\u003c/p\u003e\n\n| Feature | Description |\n|---------|-------------|\n| **Points** | Stars earned for completion |\n| **Time of Day** | Morning, Afternoon, Evening, Night, or Anytime |\n| **Completion % Per Month** | Expected completion rate (100 = daily, 50 = every other day) - used for smart reward pricing |\n| **Daily Limit** | How many times per day the chore can be completed |\n| **Requires Approval** | Parent must approve before points are awarded |\n\n### Rewards\n\n| Type | Description |\n|------|-------------|\n| **Dynamic** *(default)* | Cost auto-calculated: `Days to Goal` × expected daily earnings (based on each chore's points and completion rate) |\n| **Fixed** | Toggle \"Override Point Value\" to set a manual cost |\n| **Jackpot** | Pool stars from ALL assigned children toward one big family reward |\n\n---\n\n## Dashboard Cards\n\nCards auto-register when the integration loads. Just add them to your Lovelace dashboard - no manual resource configuration needed!\n\n### Adding Cards (Visual Editor)\n\nThe easiest way to add Choremander cards:\n\n1. Edit your dashboard and click **Add Card**\n2. Search for the card (e.g., \"choremander-child-card\") or scroll to find it under \"Custom\"\n3. Alternatively, add a **Manual** card and enter the card type (e.g., `custom:choremander-child-card`)\n4. The card will show a configuration interface - enter `sensor.choremander_overview` in the entity field\n5. Fill in any additional options (child selection, time of day, etc.) and save\n\n\u003e **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!\n\n### YAML Mode Users\n\nIf you use Lovelace in YAML mode, add these resources to your `configuration.yaml`:\n\n```yaml\nlovelace:\n  resources:\n    - url: /choremander/choremander-child-card.js\n      type: module\n    - url: /choremander/choremander-rewards-card.js\n      type: module\n    - url: /choremander/choremander-approvals-card.js\n      type: module\n    - url: /choremander/choremander-points-card.js\n      type: module\n    - url: /choremander/choremander-reorder-card.js\n      type: module\n```\n\n### Card Index\n\n| Card | For | Description |\n|------|-----|-------------|\n| [Child Card](#child-card) | Kids | Kid-friendly chore completion interface |\n| [Rewards Card](#rewards-card) | Kids | View available rewards and progress |\n| [Approvals Card](#approvals-card) | Parents | Approve or reject completed chores |\n| [Points Card](#points-card) | Parents | Manually add/remove points |\n| [Reorder Card](#reorder-card) | Parents | Organize chore display order per child |\n\n\u003e **Tip:** Create separate dashboards - one for kids (Child + Rewards) and one for parents (Approvals + Points).\n\n---\n\n### Cards for Kids\n\n#### Child Card\n\nKid-friendly interface with big colorful buttons and celebration sounds. This is the primary way children interact with their chores.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/kidCard.png\" alt=\"Kid Card\" width=\"300\"\u003e\n\u003c/p\u003e\n\n**Visual Editor:** Add `custom:choremander-child-card`, then configure the entity (`sensor.choremander_overview`), select a child, and optionally filter by time of day.\n\n\u003cdetails\u003e\n\u003csummary\u003eYAML Example\u003c/summary\u003e\n\n```yaml\ntype: custom:choremander-child-card\nentity: sensor.choremander_overview\nchild_id: a8c8376a\ntime_category: morning  # Optional: morning, afternoon, evening, night, anytime\ntitle: My Chores        # Optional\n```\n\u003c/details\u003e\n\n#### Rewards Card\n\nShows all available rewards with progress bars. Displays dynamic pricing indicators and jackpot status.\n\n**Visual Editor:** Add `custom:choremander-rewards-card`, configure the entity, and optionally filter to a specific child.\n\n\u003cdetails\u003e\n\u003csummary\u003eYAML Example\u003c/summary\u003e\n\n```yaml\ntype: custom:choremander-rewards-card\nentity: sensor.choremander_overview\nchild_id: 6ddfca70  # Optional: filter to specific child\n```\n\u003c/details\u003e\n\n---\n\n### Cards for Parents\n\n#### Approvals Card\n\nReview and approve (or reject) completed chores that require parent approval. Shows pending items grouped by time of day.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/pendingApprovals.png\" alt=\"Pending Approvals\" width=\"400\"\u003e\n\u003c/p\u003e\n\n**Visual Editor:** Add `custom:choremander-approvals-card` and configure the entity.\n\n\u003cdetails\u003e\n\u003csummary\u003eYAML Example\u003c/summary\u003e\n\n```yaml\ntype: custom:choremander-approvals-card\nentity: sensor.choremander_overview\n```\n\u003c/details\u003e\n\n#### Points Card\n\nManually add bonus points (great job today!) or remove points (consequences). Useful for situations outside the normal chore flow.\n\n**Visual Editor:** Add `custom:choremander-points-card` and configure the entity.\n\n\u003cdetails\u003e\n\u003csummary\u003eYAML Example\u003c/summary\u003e\n\n```yaml\ntype: custom:choremander-points-card\nentity: sensor.choremander_overview\n```\n\u003c/details\u003e\n\n#### Reorder Card\n\nDrag-and-drop interface to organize the order chores appear for each child. Customize the experience per kid.\n\n**Visual Editor:** Add `custom:choremander-reorder-card`, configure the entity, and select a child.\n\n\u003cdetails\u003e\n\u003csummary\u003eYAML Example\u003c/summary\u003e\n\n```yaml\ntype: custom:choremander-reorder-card\nentity: sensor.choremander_overview\nchild_id: a8c8376a\n```\n\u003c/details\u003e\n\n---\n\n\u003e **Note:** All cards require the `sensor.choremander_overview` entity. Child-specific cards also need a child selection.\n\n---\n\n## Smart Reward Pricing\n\nThe goal: **every reward should take a predictable amount of time to earn** - not random guessing.\n\n### The Problem with Fixed Prices\n\nIf 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.\n\n### How Smart Pricing Works\n\nYou set **Days to Goal** (e.g., 14 days). Choremander does the math:\n\n1. Looks at each chore's **point value** and **expected completion rate**\n2. Calculates how many points the child *should* earn per day\n3. Sets the reward cost so it takes exactly that many days\n\n```\nDaily Expected Points = Sum of (Chore Points × Completion %)\nReward Cost = Daily Expected Points × Days to Goal\n```\n\n### Why This Encourages Better Behavior\n\nHere's the key insight: **completion rate matters**.\n\nIf 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.\n\n**The incentive:** Want that reward sooner? Do the challenging stuff, not just the minimum.\n\n| Behavior | Result |\n|----------|--------|\n| Only does easy daily chores | Earns rewards at the expected pace |\n| Tackles harder/optional chores | Earns rewards *faster* than expected |\n| Skips difficult chores | Falls behind the expected pace |\n\n### Jackpot Rewards\n\nFor big family goals (vacation, museum trip), enable **Jackpot** mode. All children's stars pool together toward one shared reward - teamwork!\n\n---\n\n## Tips\n\n- **Two dashboards:** One for kids (Child + Rewards), one for parents (Approvals + Points)\n- **Completion %:** Set lower for optional/weekly chores so they don't inflate reward costs\n- **All data is local:** Nothing leaves your Home Assistant instance\n\n---\n\n## Development\n\n### Testing Changes Locally\n\nA Docker-based dev environment is included for testing changes without touching your real Home Assistant instance.\n\n#### Requirements\n- Docker and Docker Compose\n\n#### Quick Start\n\n```bash\n# Start the dev environment (first run will download HACS)\n./dev/start.sh\n\n# Open browser to http://localhost:8123\n# Login: dev / dev\n# Three test dashboards are pre-configured in the sidebar:\n#   - Kid A (morning/evening chores, progress, rewards)\n#   - Kid B (morning/evening chores, progress, rewards)\n#   - Parent (approvals, points management, reorder)\n```\n\n#### Development Workflow\n\n```bash\n# Make changes to Python files in custom_components/choremander/\n# Then restart to see changes:\n./dev/restart.sh\n\n# Make changes to JS card files - just hard refresh browser (Cmd+Shift+R)\n\n# View filtered logs while testing\n./dev/logs.sh\n\n# Get a shell inside the container\n./dev/shell.sh\n\n# Stop when done\n./dev/stop.sh\n\n# Reset to fresh state (removes auth, HACS, database)\n./dev/reset.sh\n```\n\n#### Pre-configured Test Data\n\nThe dev environment comes with:\n- **2 kids:** Krishna (25 stars) and Radha (15 stars)\n- **8 chores:**\n  - Shared: Make Bed, Brush Teeth (AM/PM), Tidy Room\n  - Krishna only: Feed the Dog, Do Homework\n  - Radha only: Water the Plants, Practice Piano\n- **5 rewards:**\n  - 30 Min Screen Time (dynamic pricing, 7 days) - shared\n  - New Video Game (50 stars, fixed) - Krishna only\n  - New Book (30 stars, fixed) - Radha only\n  - Family Movie Night (jackpot, 14 days) - shared\n  - Trip to the Zoo (jackpot, 30 days) - shared\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eLicense: MIT\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinnybad%2Fchoremander","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvinnybad%2Fchoremander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinnybad%2Fchoremander/lists"}