meitheal.io · Add-on store · Create your first task · Get help
Meitheal (/meh·hal/) is an Irish word for neighbors coming together to share the work that no single person should have to carry alone.
In your smart home, Meitheal keeps track of the work your home needs. Home Assistant already knows when the back door is still open at night, when the under-sink water filter reaches six months, or when a frost warning is due. Meitheal turns those signals — alongside recurring family routines, seasonal maintenance, and multi-step household projects — into one calm, local-first execution hub in your Home Assistant sidebar, stored in SQLite on your own hardware.
Most homes have one person quietly holding the invisible mental ledger: boiler servicing, school morning bags, bank-holiday bin changes, smoke-sensor checks, and half-finished weekend repairs. Chat reminders scroll away; corporate project trackers feel like bringing work home.
Meitheal sits naturally between Home Assistant automations and everyday household follow-through:
| Your Rule or Rhythm | The Task in Meitheal | How Your Household Follows Through |
|---|---|---|
binary_sensor.back_door stays open past 21:45 |
Close the back door — still open after 21:45 check (Critical, tagged ha-sensor) |
Appears at the top of Today and todo.meitheal_tasks until someone latches it |
Weekday 07:00 routine template |
School morning bags — lunch, books, and PE kit (with 3-step checklist) | Anyone at home can check off what is packed from the kitchen tablet or phone |
| 180-day Home Assistant counter | Replace kitchen under-sink water filter cartridge | Lands in Upcoming and syncs to your Home Assistant calendar before it is overdue |
| Multi-step seasonal prep | Winter Boiler and Heating Prep project | Tracks contractor quotes, radiator bleeding, and pressure checks in Kanban or Table |
- Start in Today: Review due work, recurring routines, carried-forward items, and evening wrap-up in one focused view.
- Plan at the right altitude: Switch between Kanban, Table, Calendar, and Timeline, or search everything instantly via Search Hub (
/orCtrl/Cmd + K). - Stay inside Home Assistant: Two-way calendar and
todo.meitheal_taskssync, Home Assistant sensors and services, Assist voice intents, webhooks, and scoped LLM/MCP agent tokens. - Use on any screen — even offline: Open through Home Assistant Ingress, launch via Companion deep links, or install the PWA with offline task queuing.
- Own your data completely: Local SQLite database covered by Home Assistant backups, plus one-click JSON, CSV, and raw SQLite exports.
| Today — Daily Focus & Routines | Household Dashboard & Focus Queue |
|---|---|
![]() |
![]() |
| Kanban & Project Board | Home Assistant-Native Settings |
![]() |
![]() |
Additional views include structured Table planning and month-grid Calendar scheduling.
Use these terms when you plan work in Meitheal:
| Term | Meaning |
|---|---|
| Pillar | A permanent, identity-based motivational anchor — the WHY behind Goals and Routines (e.g. Safe & Warm Home, Physical Longevity) |
| Principle | A behavioral boundary within a Pillar — the Non-Negotiable rules (e.g. "Keep household data local", "No screens after 9 PM") |
| Area | A life or operating domain such as Home & Safety, Family Routines, Garden, or Homelab |
| Goal | An outcome you are trying to move toward |
| Project | A bounded body of work in service of a goal (e.g. Winter Boiler and Heating Prep) |
| Task | A concrete unit of work with optional checklists, priority, effort, and Home Assistant metadata |
| Routine | Repeatable work that spawns real task instances on a daily or weekly cadence |
Some older views and integrations use earlier names. The glossary explains the current model.
- Open Settings → Apps → Install app in Home Assistant (called Add-ons → Add-on Store in earlier Home Assistant releases).
- Open the top-right ⋮ menu and select Repositories.
- Add
https://github.com/ryan-winkler/meitheal-ha-addon. - Select Meitheal (or Meitheal Canary to preview upcoming builds).
- Select Install, then Start, and enable Show in sidebar if desired.
- Select Open web UI.
See the add-on setup guide and Canary guide for full configuration and backup notes.
Meitheal uses two linked repositories so Home Assistant appliances stay fast and lightweight during Store refreshes:
| Repository | Purpose | Contents | Who Uses It |
|---|---|---|---|
| meitheal (this repo) | Application source & CI | Astro SSR web app, DDD domain packages, E2E test suites, Dockerfiles, and release pipelines (dev is the default branch). |
Contributors, reviewers, and CI/CD pipelines. |
| meitheal-ha-addon | Home Assistant App Store catalog | Lightweight Store manifests (config.yaml), brand icons, translations, screenshots, and setup guides (~2 MB). |
Home Assistant Supervisor & users installing Meitheal. |
Why retain meitheal-ha-addon separately?
Home Assistant Supervisor clones the full Git repository onto user hardware when adding a store URL and runs git pull on every Store refresh. Keeping meitheal-ha-addon lightweight stops low-memory devices (such as Home Assistant Green or Raspberry Pi) from downloading full monorepo history, packages, and test suites just to check for add-on updates.
Follow the local setup to open Meitheal in your browser and create a task with a disposable SQLite database. Use Home Assistant or the checked-in devcontainer for voice, companion app, ingress, and automation features.
The optional Home Assistant custom integration adds todo.meitheal_tasks, task count sensors, and native automation actions. Set it up once the add-on is running:
- Install the Meitheal integration.
- Open Settings → Devices & Services in Home Assistant and configure the discovered Meitheal entry.
- Enter a scoped Meitheal agent token when prompted (Settings → AI & Agent Access inside Meitheal).
- In Settings → Voice assistants → Expose, choose whether Assist can use
todo.meitheal_tasks. Grant Read Tasks and Create & Update Tasks for voice capture and completion.
On Home Assistant Core 2026.11 or later, an active administrator can also enable Meitheal Tasks (read only) in a conversation agent's LLM API settings to search and summarize tasks safely. External automation tools (n8n, Node-RED, MCP clients) can use separate scoped tokens.
Integration credentials · Agent & MCP guide
| Layer | Stack |
|---|---|
| Runtime | Astro SSR web application running as a Home Assistant add-on behind Supervisor Ingress |
| Persistence | Local SQLite storage (/data/meitheal.db) via Node.js built-in SQLite (node:sqlite DatabaseSync) repositories |
| Domain Model | Bounded DDD packages (domain-auth, domain-tasks, domain-strategy, domain-observability, integration-core) |
| Interface | Accessible dark & light themes (Geist Variable + JetBrains Mono), installable PWA, and keyboard-first navigation |
| Integrations | Home Assistant WebSocket/REST, calendars, todo.meitheal_tasks, Grocy, webhooks, A2A, and OpenAPI-driven MCP tools |
| Deployment | Multi-arch (amd64, aarch64) container on the same host as Home Assistant with AppArmor isolation |
- Create your first task
- Set up the Home Assistant add-on
- Open Meitheal in the Home Assistant Companion app
- Install the web app and use it offline
- Find tasks, views, and settings with Search Hub
- Design system, brand tokens, and appearance
- Browse all operational and KCS guides
- Keep household data local on hardware you control.
- Make the Home Assistant Ingress and Companion path work first.
- Keep data portable through Home Assistant backups and open exports.
- Update the user guide in the same change whenever workflows evolve.
- Contribute a change
- Project governance and roadmap
- Architecture overview and security assurance case
- Use automations and agents with Meitheal
- Community conduct
- Support
- Report a security problem privately
Meitheal is independent and community-driven. Financial support helps fund infrastructure, accessibility testing, hardware qualification, and continuous development:
Meitheal is free software under the GNU Affero General Public License v3.0 only (AGPL-3.0-only). You can use, study, modify, and share it. If you distribute Meitheal, or let others interact with a modified version over a network, you must offer them its complete source under the same license. A commercial license is available for uses that cannot meet those terms. The optional Home Assistant integration and automation integration have separate licenses. The compatibility API remains separately licensed and outside this release. The distribution license covers published add-on images.




