ChorePilot

ChorePilot, your smart-home AI agent assistant: local-first, runs your appliances and keeps the household's chores fair.

You talk to it (terminal, Telegram, a web dashboard, or any MCP agent) and it does two jobs:

1. It runs the house. Dishwasher, washer, dryer, lights, blinds, thermostat / AC, water heater, sprinklers, coffee machine, oven, fridge, robot vacuum, air purifier, humidifier, speakers and TVs, EV charger, door locks, garage door, alarm panel. The model only asks; a policy engine decides, from who is asking and how risky the action is.

2. It keeps the chores fair. People, chores, schedules, rotations, points, reminders and approvals, and where it can it verifies a chore from the device itself: when the dishwasher finishes, "Run the dishwasher" is done, the credit goes to whoever started it, and "Empty the dishwasher" opens for the next person in that chore's rotation.

The model runs on your own hardware through any OpenAI-compatible server (llama.cpp's llama-server, Ollama, LM Studio, vLLM). Everything stays local: a SQLite file, an append-only audit log, no account, no telemetry. It is stdlib-only Python, so it installs anywhere from a Pi Zero to a NAS, and whoever installs it owns it: chorepilot setup creates your household with you as the owner. Nothing about anyone else's home is baked in.

ChorePilot started as Dishsoaker3000, a joke about running an LLM on a dishwasher. Then the LLM got to actually wash the dishes, then to say whose turn it is to empty them. The LLM-on-anything bits still work (below), and dishsoaker and wash are aliases for chorepilot.

Features

• Local-first. Your model, your box, your data. A 1.5B-4B instruct model is enough.

• One safety model everywhere. Terminal, Telegram, dashboard and MCP agents all go through the same policy engine: read / low / water-heat / security tiers, roles, confirmations, a kids' approval queue, owner PIN or TOTP for security actions.

• Device-verified chores. Rotations (round robin, least points, weekly), deterministic schedules, follow-ups, points, quiet hours, reminders.

• Talks to what you have. Home Assistant (so anything HA supports, including Matter), the official Home Connect API (Bosch, Siemens, Neff, Gaggenau), MQTT / ESPHome, and a simulator to try everything first.

• First-run wizard. chorepilot setup: owner + PIN + authenticator QR code, members, model detection and a hardware-based model recommendation, Home Assistant entity discovery, Home Connect login, Telegram bot walkthrough, MCP tokens, sensible default chores.

• Works with Grok Bot / Claude / any MCP client, without ever letting an agent unlock a door.

• Runs as a service: chorepilot run starts everything you configured; pipx, Docker, a Home Assistant add-on, systemd and launchd files are included.

Related MCP server: guardian-policy-mcp

Quick start

pipx (any Linux / macOS / Raspberry Pi OS):

pipx install chorepilot          # once on PyPI; today: pipx install . (in a checkout) or a git URL
chorepilot setup                 # the wizard: you become the owner
chorepilot run                   # Telegram + device events + MCP + the dashboard
chorepilot service install       # optional: keep it running (systemd user unit / launchd agent)

Docker (next to Home Assistant or anything else):

docker compose build
docker compose run --rm chorepilot setup     # interactive, state in ./data
docker compose up -d                         # dashboard on http://127.0.0.1:8771

Home Assistant add-on: add packaging/homeassistant/ as an add-on repository (run its sync.sh first when building from a checkout), set your name and PIN in the options and start it. It reaches Home Assistant through the Supervisor (no token to paste) and maps your entities on first start. See packaging/homeassistant/chorepilot/DOCS.md.

Just trying it? chorepilot setup --simulated adds a simulated house (every device type), so nothing real is touched.

What chorepilot setup asks

Every step can be re-run on its own (chorepilot setup devices, setup telegram, ...) and chorepilot setup status shows what is configured. Everything works non-interactively too:

chorepilot setup --non-interactive --household "Our home" --owner Alex --owner-pin 2468 --totp \
    --member Sam:adult --member Jordan:kid --model-url auto \
    --ha-url http://homeassistant.local:8123 --ha-token "$HA_TOKEN" --mcp-client claude-desktop

Ownership. The person who runs setup is the owner and the default identity at this machine's terminal. Several owners are supported: adding one needs an existing owner's PIN or TOTP (chorepilot setup owner, or people set-role <name> --role owner), and chorepilot people transfer-owner <name> hands the household over (--keep to stay a co-owner). The last owner can never be demoted by accident.

A fresh install, recorded

This ran on an M4 Mac in an empty temporary HOME (scripts/fresh_install_demo.sh) with a Qwen2.5-1.5B-Instruct Q4_K_S GGUF (0.94 GB) on llama-server, against the simulated house. Shortened, not edited:

$ chorepilot people list
nobody yet: run `chorepilot setup` (you become the owner)

$ chorepilot setup --non-interactive --household "Our home" --unit F --owner Alex --owner-pin 2468 --totp \
    --member Sam:adult:1357 --member Jordan:kid:1111 --member Riley:kid \
    --model-url http://127.0.0.1:8092 --simulated --mcp-client claude-desktop --chores default
== The household and its owner ==
  Alex is the owner of Our home
  PIN set for Alex (stored as a PBKDF2 hash)
  Scan this with your authenticator app (Google Authenticator, Aegis, 1Password, Authy ...):
  [QR code]
== Household members ==
  added Sam (adult)
  added Jordan (kid), quiet hours 21:00-07:00
  ...
== The local model ==
  using http://127.0.0.1:8092
== Devices ==
  added 19 simulated devices
== Outside agents (MCP) ==
  claude-desktop acts as Alex (owner). Token, shown once: cp_...
== Chores ==
   [1] Run the dishwasher       daily at 19:30                       Alex, Sam, Jordan, Riley
   [2] Empty the dishwasher     on demand                            Jordan, Riley
   [3] Laundry                  every monday and thursday at 18:00   Alex, Sam
   ...

$ chorepilot ask "wash my dishes"                     # no --as: the person who set it up
  [tool call ] start_program({"appliance": "dishwasher", "program": "auto"})
  ?? Start auto on the dishwasher (Bosch SMV6ZCX42E, simulated)? It uses water and heat. [y/N] y
  [house     ] {"ok": true, "state": "running", "remaining": "2 h 39 min", "program": "auto"}  (policy: confirm, tier 2)
Your dishes are now being washed in the dishwasher. It will take approximately 2 hours and 39 minutes.
  [done      ] 4.1s, 2 model turn(s), 77.0 tok/s

$ chorepilot ask "who has the dishwasher this week?" --as Sam
  [tool call ] who_has({"chore": "Run the dishwasher"})
Alex has the dishwasher this week. It's due today at 19:30.

$ chorepilot events poll                              # ... once the dishwasher has finished
  [event     ] dishwasher: finished
  [chores    ] 'Run the dishwasher' done by Alex, verified by the dishwasher.
  [chores    ] 'Empty the dishwasher' is now open for Jordan.

$ chorepilot ask "open the garage door"
  [tool call ] garage_door({"device": "garage", "action": "open"})
  ## Open the garage? Alex, enter your ChorePilot PIN or TOTP code:
  [house     ] {"ok": true, "device": "garage", "action": "open", "state": "open"}  (policy: second_factor, tier 3)

$ chorepilot ask "close the garage door" --as Jordan  # a kid: closing is tier 1
  [house     ] {"ok": true, "device": "garage", "action": "close", "state": "closed"}  (policy: allow, tier 1)

$ chorepilot ask "charge the car" --as Jordan
  [tool call ] ev_charger({"device": "car_charger", "action": "start_charging", "current": 32})
  [house     ] {"ok": false, "queued_for_approval": 1, ...}  (policy: approval, tier 2)
I've sent the request to the parents to approve the charging of your car.

# Sam signs in to the dashboard with a PIN and presses Approve:
approve #1: approved {'state': 'charging', 'current': 32, 'power_kw': 7.36, 'session_kwh': 0.0}

$ chorepilot ask "disarm the alarm" --as Sam
  [house     ] {"ok": false, "error": "only the owner can do that (security action)"}  (policy: deny, tier 3)

$ chorepilot ask "turn the music up to 100" --as Riley
  [house     ] {"ok": false, "error": "volume must be 0..80 (got 100)"}

$ chorepilot run --check
  events    19 device(s)
  telegram  off (no bot token: chorepilot setup telegram)
  mcp       1 token(s)
  web       http://127.0.0.1:8771/

Every model turn took 1 to 4 s at 77 to 99 tok/s. The audit log has one line per call, with the dashboard approval recorded as source: web and the charge it started as Sam's.

Safety model

The policy engine decides every action from the authenticated person: who is at the terminal, whose Telegram account sent the message, who signed in to the dashboard, whose token an MCP client holds. It never decides from anything the model says.

• The model can never supply a code. A pin / code argument from the model is rejected; a lock's or alarm panel's own code lives in config and is masked even in --dry-run output.

• Three wrong codes lock tier 3 for 10 minutes; five wrong dashboard PINs lock sign-in.

• Never on a schedule, never from an agent: tier 3 is refused for source=schedule and for every external agent, whatever house.json says.

• Vendor interlocks always win: door open, remote start not armed at the machine, lock jammed, garage obstruction, alarm triggered, no car plugged in, water tank empty.

• Limits are hard: sprinkler runs have a duration and a cap (the close is scheduled when the valve opens), the water heater has a scald ceiling, the EV charger a current range, speakers a volume cap, humidifiers a mould-safe band.

• Rate limits: one start per device per minute, six writes per 10 minutes.

• Audit: every call goes to ~/.config/chorepilot/audit.log (append-only, 0600) with the person, the source (cli / telegram / web / mcp) and the MCP client; codes are written as ***.

• Secrets live in 0600 files under ~/.config/chorepilot or in the environment, never in house.json. The model never sees URLs, tokens, PINs or codes.

• No open ports by default: Telegram uses outbound long polling; the dashboard and MCP bind 127.0.0.1 unless you ask otherwise (and then they warn).

Supported devices

One small plugin per device type in chorepilot/devtypes/. docs/DEVICES.md has every device class, the Home Assistant services, Matter device types, vendor APIs (with primary sources) and the full per-action tier table.

Adapters live in chorepilot/adapters/: simulated (the default, safe), ha (the universal adapter), matter (through HA's Matter server), mqtt (ESPHome) and homeconnect. A new appliance type is one module, and no new adapter if HA already exposes it; a user plugin can live in ~/.config/chorepilot/devtypes/.

The web dashboard

chorepilot web (or as part of chorepilot run) serves the household app on http://127.0.0.1:8771. Since 0.7 it is dark first, with a technical look built for people who run their own models on their own hardware: a live house-status band, a Local AI panel (model, tokens/s, time to first token, context, GPU memory, host), Ask the house as a traced console, spec-panel device tiles and a chore leaderboard. The typeface is IBM Plex Sans (OFL, self-hosted). It is hand-written HTML, CSS and JavaScript shipped inside the package: no CDN, no build step, no npm, and the Python side is still the standard library. It works on a phone, a tablet and a desktop, in light and dark mode, and installs to a phone's home screen.

• Home: a "right now" line (what is running and how long it has left, the temperature inside, anything unlocked or waiting for a decision), Ask the house (type, or speak where the browser supports it), what is happening now, your chores today, the family's week.

• Ask the house goes through exactly the same agent and policy as chorepilot ask and Telegram. Water or heat comes back as an inline card the signed-in adult taps; a strong confirmation asks for the typed phrase; unlocking asks for the owner's PIN again; a kid's request goes to the approvals queue. Every step and the result are shown, and logged. Without a model it says so in one line and the device controls keep working.

• Devices: tiles grouped by room, live state, a one-tap icon where it makes sense (lights, locks, blinds, the vacuum), and a detail sheet with the device's full controls: a big stepper for thermostats and water heaters, sliders for brightness / position / volume, a progress ring with time left for the dishwasher, washer, dryer and sprinklers, the program picker with options. All of it is drawn from the device-type registry, so a plugin type gets a tile and a sheet without any web code. Every control goes through the policy tiers.

• Chores: each person's week (a progress ring, points, streak, what is due today), due today / coming up / waiting for a parent, rotations with this week and next week, and "done this week" with a badge when a device verified it. Adults reassign with one tap.

• Approvals: who asked for what and why it needs a parent, Approve / Deny; MCP agents waiting for your yes show up here too (mcp.confirm_channels can leave the dashboard out).

• Activity: a readable, day-grouped timeline ("Sam started eco on the dishwasher", "Jordan asked to water the lawn sprinkler, sent to a parent"); the raw audit log is one tap away.

• Setup in the browser: on a fresh install, open the page on the ChorePilot computer and a short wizard creates the owner and PIN, adds people, links Home Assistant (with a checklist of the entities it found), Home Connect (device-flow sign-in with a QR code), MQTT or the simulated devices, finds or sets the model and tests it, adds default chores, and shows the Telegram link QR codes and MCP tokens. It calls the same code as chorepilot setup, which still works as before.

Security, unchanged or stricter: sessions are HttpOnly, SameSite=Strict cookies; every write needs the CSRF header; Host and Origin are checked; five wrong PINs lock sign-in; a strict Content-Security-Policy (no inline script or style, nothing from other origins). A dashboard "yes" is a single-use token for exactly the action the server asked about. The first owner can only be created from the machine itself, never through a proxy or tunnel.

Away from home

ChorePilot never relays anything through a cloud of ours. Two supported ways in, both HTTPS:

# Tailscale (recommended): only your own devices can reach it
tailscale serve --bg 8771
chorepilot web --public-url https://<this-machine>.<tailnet>.ts.net

# Cloudflare Tunnel, with Cloudflare Access (email code / company SSO) in front
cloudflared tunnel run --url http://127.0.0.1:8771 chorepilot
chorepilot web --public-url https://home.example.com

--public-url (or web.public_url in house.json, which Settings > Away from home writes) accepts that host name and origin, marks the cookie Secure and sends HSTS on requests that came through it. The dashboard keeps listening on 127.0.0.1 only. Details: docs/REMOTE-ACCESS.md.

Chores

chorepilot chores list | who dishes | done dishes --as Jordan | assign dishes Riley --week
chorepilot chores add "Feed the cat" --schedule "daily at 08:00" --rotation Jordan,Riley --points 1
chorepilot chores add "Dishes" --schedule "daily at 19:30" --rotation Jordan,Sam,Riley,Alex \
    --rotate week --verify dishwasher.finished --followup "Empty the dishwasher" --points 2
chorepilot chores remind | points | swap dishes Jordan Riley | rm "feed the cat"
chorepilot approvals list | approve 3 --as Alex | deny 4 --as Sam
chorepilot events push | poll | watch -i 30 | emit vacuum finished | list

• Schedules are parsed without a model, so they behave the same every time: daily at 8pm, every monday and thursday at 18:00, weekdays, every 3 days, every other tuesday, 3 days after done, on demand, or an RRULE subset.

• Rotations: round_robin, least_points (fairness), fixed, random, claimable; per instance or per week.

• Verification: --verify <device>.<event> (dishwasher.finished, vacuum.finished, lawn_sprinkler.finished, car_charger.finished ...). A kid's self-report on a --needs-approval chore waits for a parent. Follow-ups open for the next person in their chore's rotation.

• Events are pushed where the device can push (Home Assistant websocket, the Home Connect event stream, MQTT), with polling for the rest, so a verified chore closes seconds after the machine finishes.

• A deterministic tool router gives the model only the tools a request needs: "who has the dishes this week?" gets only chore tools, so a 1.5B model can't wander off and start the dishwasher.

Telegram

chorepilot setup telegram walks you through it: in Telegram, open @BotFather, send /newbot, pick a name and a username ending in bot, and paste the token. Each person then links their own account once with a one-time code (/link ABCD2345, 10 minutes, single use; new codes with chorepilot telegram link <name>). After that, a message is answered by your local model as that person, with that person's role:

• water / heat asks with Yes / No buttons that only the asker can press;

• tier 3 asks for the owner's PIN or TOTP only in a private chat, deletes the message immediately, and never logs it or shows it to the model; in a group it refuses;

• parents get the approval queue with Approve / Deny buttons; device-verified completions and reminders are announced; /chores, /done <chore> and /approvals work without a model.

Works with Grok Bot / Claude / any MCP client

chorepilot mcp exposes the house and the chore board as an MCP server (stdio and streamable HTTP), so xAI's Grok Bot, Claude Desktop, Claude Code, OpenClaw or any MCP client can drive it, through the same policy engine with source mcp:

chorepilot setup mcp                                    # or: chorepilot mcp token add Alex --client claude-code
chorepilot mcp --http                                   # http://127.0.0.1:8770/mcp, bearer token required
chorepilot mcp --as Alex                                # stdio, for clients that start the server
claude mcp add chorepilot -- chorepilot mcp --as Alex --client claude-code

Claude Desktop (claude_desktop_config.json):

{"mcpServers": {"chorepilot": {"command": "chorepilot",
                               "args": ["mcp", "--as", "Alex", "--client", "claude-desktop"]}}}

Grok Bot runs on xAI's cloud, so it needs a public HTTPS URL: put a tunnel (Cloudflare Tunnel, Tailscale Funnel) in front of 127.0.0.1:8770, then add a custom MCP connector with that URL and the header Authorization: Bearer cp_... (in chat, or at grok.com/connectors). Make one token per agent and revoke it when you stop using the agent (xAI connectors docs). If an agent also has a shell on the ChorePilot machine, set "mcp": {"confirm_channels": ["telegram"]} so a yes can only come from your phone.

Grok is a trademark of xAI, and Claude is a trademark of Anthropic. ChorePilot is an independent project and is not affiliated with either company.

Use it from Hermes Agent

ChorePilot installs as a plugin for Hermes Agent (Nous Research), the same way Hermes installs any plugin:

# on the ChorePilot machine
chorepilot mcp token add Alex --client hermes        # shown once, stored hashed
chorepilot run                                       # MCP on 127.0.0.1:8770

# in Hermes (asks for CHOREPILOT_URL and CHOREPILOT_TOKEN)
hermes plugins install WestWaters/ChorePilot/hermes/chorepilot --enable

Hermes gets seven chorepilot_* tools (status, chore board, who has, done, whoami, the house's tool list, and a call for every device and chore action) and a chorepilot:household skill. Same rules as every other channel: water/heat actions wait for the person's own yes in Telegram or on the dashboard, a kid's token goes to the parents' queue, unlocking is never available. Hermes on another machine: tailscale serve --bg 8770 and https://<machine>.<tailnet>.ts.net/mcp, or --lan on a trusted network. Prefer no plugin? hermes mcp add chorepilot --url http://127.0.0.1:8770/mcp works too. Details, small-model tips and a test run: docs/HERMES.md.

Hermes Agent is a project of Nous Research; ChorePilot is not affiliated with it.

Configuration and files

Everything lives in ~/.config/chorepilot/ (override with CHOREPILOT_CONFIG_DIR):

Environment variables win over files (HA_URL, HA_TOKEN, CHOREPILOT_TELEGRAM_TOKEN, CHOREPILOT_LLM_URL, ...), and every legacy DISHSOAKER_* name still works. Bosch owners: docs/SETUP-bosch-home-connect.md walks through a Home Connect dishwasher, washer and dryer end to end, including the washer-then-dryer chain.

FAQ

Do I need a GPU or a cloud account? No. A 1.5B-4B instruct model at Q4 runs on a laptop, a mini PC or a Pi 5; chorepilot recommend tells you what fits. ChorePilot never calls a cloud model unless you point it at one.

Do I need Home Assistant? No, but it is the easiest way to reach most brands. Home Connect appliances and MQTT / ESPHome devices work without it, and the simulator works with nothing.

Can the AI unlock my door, open the garage or disarm the alarm? Only you, the owner, can, and only by typing your PIN or TOTP code yourself at the prompt or in a private Telegram chat. The model can't pass a code, schedules can't do it, and outside agents are always refused.

Can my kids use it? Yes. Kids can do low-risk things (lights, the vacuum, closing the garage, arming the alarm; the owner can turn that off), and anything with water, heat or a lot of energy goes to a parent's approval queue. Their self-reported chores can require a parent's OK too.

What happens if the model gets it wrong? It can only call the tools the router gave it, the arguments are validated strictly against the device type, the policy engine and the device's own interlocks run before anything is sent, and --dry-run shows the exact requests.

Which model should I use? Any instruct model with tool calling. chorepilot setup model detects what is running and suggests a size for your hardware; Qwen2.5 / Qwen3 instruct models from 1.5B up work well.

Is my data shared? No. There is no account and no telemetry. Telegram (if you enable it) sees the chat messages you send your own bot; Home Connect (if you use it) is Bosch's cloud API for your own appliances.

Can I move to another machine? Copy ~/.config/chorepilot/ (it contains secrets; keep it private).

LLMs on anything: the Dishsoaker3000 bits

ChorePilot still does the job it started with. It looks at a device, tells you which model fits, at what quant and context and at what speed, then runs it under a memory guard that never lets the machine run out of RAM, alone or as part of a LAN "wash crew": a llama.cpp RPC cluster in which the dishwasher holds a few layers.

chorepilot probe [--profile dishwasher-1g|pi-zero-2w|pi-5-8gb|...]   # RAM, cores, GPU, disk, link
chorepilot recommend [--catalog] [--worker dishwasher-1g]          # what fits, how fast
chorepilot plan --model synthetic:27b@3.0 --profile pi-5-8gb --worker pi-5-8gb --worker dishwasher-1g
chorepilot serve [--worker --lan] [--scan] [--spec draft-mtp]      # local / RPC worker / host
dishsoaker wash --profile dishwasher-1g --cycle quick --prompt "say hello from inside a dishwasher"
wash "wash my dishes" --yes                                        # the original appliance path
chorepilot control status|start|pause|resume|cancel|programs|init|sim|chains|tools|login

Splitting a model across boxes buys capacity, not speed; plan shows the arithmetic, and docs/RESEARCH.md and docs/DESIGN.md have the numbers. llama.cpp's RPC server is unauthenticated: workers bind 127.0.0.1 unless you pass --lan; use that only on a network you trust, never port-forwarded.

Moving from Dishsoaker3000: ~/.config/dishsoaker is copied to ~/.config/chorepilot on first run (the old directory is left alone), an existing control.json keeps working, and every DISHSOAKER_* environment variable is still read.

Docs

• docs/DEVICES.md: device classes, HA / Matter / vendor APIs, risk tiers

• docs/DESIGN.md: architecture, modules, memory and speed models

• docs/CONTROL.md: appliance control per brand

• docs/SETUP-bosch-home-connect.md: Bosch Home Connect appliances, end to end

• docs/RESEARCH.md: devices, bandwidth and model-fit research

• docs/UI-RESEARCH.md: what the best home, chore and assistant apps do, and how the dashboard answers them

• docs/REMOTE-ACCESS.md: using the dashboard from your phone or office, safely

• docs/HERMES.md: the Hermes Agent plugin and MCP setup

• CHANGELOG.md

Licence

Apache-2.0, see LICENSE. The licence is a single file, so a different licence (for example a commercial one) can replace it later; pyproject.toml reads it from that file.

ChorePilot is not a safety or compliance system, and nothing here is legal advice. Smart plugs are for monitoring only: never switch the mains of an appliance that heats or holds water.