Homebase

A unified household assistant that runs as an OpenClaw skill. Built for families

who want one place for the calendar, the meal plan, the grocery list, the

school inbox, and the morning routine — without writing any code per family.

Features

• Morning briefing — daily 7 AM weather + schedule + kids meal + school snack digest. Pre-flight health check, output validation, 30-day reliability tracker.
• Calendar — Google Calendar sync + natural-language event creation.
• Kids meals — config-driven per-kid breakfast/lunch/snack rotation with allergy and texture rules. Avoids same-meal-twice patterns from history.
• Weekly meal planner — Saturday 6 PM draft, family revises by reply, Sunday 9 PM auto-lock. Max 2 revisions then auto-locks.
• School email monitor — every 2 hours during school, parses Gmail for school flyers + PDF attachments, dedupes, surfaces important items.
• Receipt + media watcher — receipt photos sent to WhatsApp get classified by caption keywords, then read by the OpenClaw agent's native vision and logged to a per-restaurant rating ledger.
• Shopping list — per-store ("Costco", "Indian", "Target") item lists with atomic writes.
• Health tracker — Tylenol/ibuprofen dose log per kid with weight-based safety limits and minimum-interval enforcement.
• Trip detector — scans the calendar for upcoming trips, classifies the destination (mountain/beach/desert/urban), pulls weather, composes prep notes from per-kid profiles.

Architecture

Python tools return data. The OpenClaw agent (model-agnostic — Claude, Gemma,

GPT, Llama, whatever OpenClaw is configured with) composes and delivers all

user-facing messages. Python never sends WhatsApp and never calls any LLM. Every Python

state file is written atomically (tempfile + fsync + rename) so a mid-write

crash never leaves a corrupt JSON behind. Cron entry points have a top-level

try/except so a crash always emits a parseable status object instead of

silently swallowing the run.

Secrets handling

This skill needs Google OAuth credentials (GOOGLE_CLIENT_ID,

GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN) to read your Google Calendar

and school Gmail. No other API keys, no LLM keys, no third-party tokens.

Credentials are read from environment variables. On macOS they can

optionally be migrated into the system Keychain via migrate_to_keychain.py

and then removed from .env. The skill never transmits credentials anywhere

except to Google's official OAuth endpoint via google-auth-oauthlib.

The only outbound network calls this skill makes are to documented services

required for its features:

• Google OAuth + Gmail + Calendar APIs (*.googleapis.com) for the calendar

sync, school email monitor, and credential refresh

• Open-Meteo (api.open-meteo.com) for weather forecasts in the morning

briefing and trip detector — no API key, no account, no PII sent

There is no telemetry, no analytics, no third-party tracking, no calls to

any other domain.

All household state (calendar cache, meal history, health log, kid profiles,

restaurant ratings, shopping list, briefing reliability tracker) is stored

as local JSON files in household/ and calendar_data/. Nothing leaves

your machine.

File permissions. .env should be chmod 600 (the included

setup_check.py verifies this). The household/ and calendar_data/

JSON files inherit your user umask — they're owned by the user running

OpenClaw and not accessible to other local users on a default macOS or

Linux setup. If you're on a multi-user system, audit those paths.

About the launchd plist

com.openclaw.daemon.plist in this repo is a **template for the OpenClaw

gateway daemon**, not for Homebase code. The plist runs

/usr/local/bin/openclaw start --foreground, which is what keeps the

WhatsApp bridge alive across logins. It does NOT run any Homebase Python

directly.

It's optional. You only need it if you want WhatsApp delivery to survive

a logout or reboot. Without it, OpenClaw runs only while your terminal

session is active. If you install it, it lives at

~/Library/LaunchAgents/com.openclaw.daemon.plist and can be removed at

any time with launchctl unload.

Requirements

• Python 3.12+
• Google Cloud project with Gmail + Calendar APIs enabled
• WhatsApp delivery via OpenClaw (no direct integration in this skill)
• Image vision is handled by the OpenClaw agent's native capability — no local LLM dependency in this skill

Setup

1. cp config.example.json config.json and fill in your family.
2. Set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REFRESH_TOKEN in your environment, or migrate them into the macOS Keychain via python migrate_to_keychain.py.
3. pip install -e . (uses pyproject.toml).
4. python -m pytest should report all tests passing.
5. python setup_check.py runs a config + auth sanity check.

Limitations

• macOS Keychain integration is best-effort on macOS only; other platforms fall through to env vars.
• The daily briefing assumes one Google Calendar; multi-calendar merging is not yet supported.

Troubleshooting

• Briefing missing weather — Open-Meteo rate limit. The reliability tracker in household/briefing_reliability.json will flag the day as degraded.
• Gmail auth error — python core/reauth_google.py to re-mint the refresh token. The school email monitor will WhatsApp you exactly once when this happens, then go silent until fixed.
• JSON file corrupt — atomic writes prevent this in normal operation. If it happens anyway (e.g., disk full), delete the file; the loader recreates an empty one.

License

MIT