██╗  ██╗ ██████╗ ██╗   ██╗███████╗███████╗██╗  ██╗███████╗███████╗██████╗ ██╗███╗   ██╗ ██████╗
██║  ██║██╔═══██╗██║   ██║██╔════╝██╔════╝██║ ██╔╝██╔════╝██╔════╝██╔══██╗██║████╗  ██║██╔════╝
███████║██║   ██║██║   ██║███████╗█████╗  █████╔╝ █████╗  █████╗  ██████╔╝██║██╔██╗ ██║██║  ███╗
██╔══██║██║   ██║██║   ██║╚════██║██╔══╝  ██╔═██╗ ██╔══╝  ██╔══╝  ██╔═══╝ ██║██║╚██╗██║██║   ██║
██║  ██║╚██████╔╝╚██████╔╝███████║███████╗██║  ██╗███████╗███████╗██║     ██║██║ ╚████║╚██████╔╝
╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚══════╝╚══════╝╚═╝  ╚═╝╚══════╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═══╝ ╚═════╝

Housekeeping

A self-hosted home maintenance planner. List your appliances, yard and cars, and get a short, fixed list of what to do each week, based on their manuals, your climate and what you've already done.

More about it: individuation.dev/projects/housekeeping.

Features

• Inventory of everything that needs care. Appliances, home systems, outdoor features, plants and lawn, and vehicles with model year and odometer reading.
• Add items by photo. Under Add item → Scan a label, take a picture of the rating plate, VIN sticker or plant tag. Claude fills in the kind, make and model, and year, plus specs that matter for care, such as filter size or refrigerant. It only fills in a year that's printed or decoded from a date code or VIN, and says which. The photo is kept with the item.
• A plan with a fixed size. Choose how many tasks you want per week (or per day). The scheduler picks the most urgent ones and keeps the list stable for the period. Snooze or pause a task to free its slot.
• Recurring jobs and one-off tasks. Every N days (furnace filter, 90 days), seasonal windows (clean gutters, Oct–Nov), every N miles with a time cap (oil change, 5,000 mi or 6 months), or just once, optionally by a deadline (fix the fence gate by Friday).
• Suggestions from Claude, approved by you. Claude proposes a schedule for each item based on its make, model, year and your climate. Nothing reaches your plan until you approve it.
• Reads the manuals. Find manuals searches the web for an item's owner's manual and downloads it. Spec sheets and parts pages are discarded. You can also upload PDFs or photos of a data plate, or paste a link. Claude notes the maintenance intervals with page numbers, part numbers and filter sizes, and suggestions follow the manufacturer's intervals.
• Imports your own checklist. Under Tasks → Import a checklist, paste it, or upload a PDF or photo, and each recurring item becomes a task.
• A logbook. Every completion is recorded with the date, odometer reading and notes.
• Self-hosted and private. One container and a SQLite file. No account and no telemetry. It uses your system font, and its only outside requests go to the Anthropic API and to the public websites it downloads manuals from.
• Works on a phone. Responsive layout with a bottom tab bar, light and dark themes, and it can be installed to your home screen.

Quick start (Docker)

You need Docker with Compose v2.24 or later, and an Anthropic API key for the Claude features. Images are published for amd64 and arm64, so it also runs on a Raspberry Pi 4 or later and on Apple silicon.

mkdir housekeeping && cd housekeeping
curl -fsSLO https://raw.githubusercontent.com/ChrisThoma/housekeeping/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/ChrisThoma/housekeeping/main/.env.example -o .env
# open .env and add your ANTHROPIC_API_KEY
docker compose up -d

Open http://localhost:8000. The first screen walks you through setup.

By default only this computer can reach it. To use it from your phone or other devices, see Running it on a server.

Your data lives in the housekeeping_housekeeping-data Docker volume: the SQLite database plus every downloaded or uploaded document. To update to the latest release:

docker compose pull && docker compose up -d

To stay on one version, set HOUSEKEEPING_VERSION=0.2.0 in .env. Without Compose:

docker run -d --name housekeeping -p 127.0.0.1:8000:8000 --env-file .env \
  -v housekeeping_housekeeping-data:/data --restart unless-stopped ghcr.io/christhoma/housekeeping:latest

This uses the same volume name as Compose, so the backup commands below work for both.

To build from source instead, clone the repository and run docker compose up -d --build. In a clone, docker-compose.override.yml swaps the published image for a local build.

Back up and restore

Stop the app first, so the database isn't copied or replaced while it's being written. With docker run, use docker stop housekeeping and docker start housekeeping instead.

# Back up to ./housekeeping-backup.tar.gz
docker compose stop
docker run --rm -v housekeeping_housekeeping-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/housekeeping-backup.tar.gz -C /data .
docker compose start

# Restore
docker compose stop
docker run --rm -v housekeeping_housekeeping-data:/data -v "$PWD":/backup alpine \
  tar xzf /backup/housekeeping-backup.tar.gz -C /data
docker compose start

The volume name is the same wherever you put the folder. Check it with docker volume ls before restoring: Docker creates a missing volume silently, empty.

This is the beginning of the README. Read the rest at the original. Read the full README ↗