homebase

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.
• Club Studio watcher (optional, club_studio.enabled in config.json) — polls Gmail every 15 min for Club Studio Fitness booking/cancellation/waitlist emails, announces them to configured WhatsApp groups, and keeps calendar entries in sync. A separate recommender/scraper component (features/club_studio/scraper.py) uses Playwright browser automation against clubstudiofitness.com's public class schedule to suggest classes — this is a real third-party site outside the Google/Open-Meteo scope described below; see Secrets handling.

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 outbound network calls this skill makes:

• Google OAuth + Gmail + Calendar APIs (*.googleapis.com) for the calendar sync, school email monitor, Club Studio Gmail watcher, 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
• clubstudiofitness.com — only if club_studio.enabled is true. The recommender (features/club_studio/scraper.py) uses Playwright to load the public class-schedule page. Its own docstring says this is done "to bypass bot protection" — that's a real, disclosed capability, not a hidden one: browser automation against a third-party site, run under a separate system Python interpreter. Leave club_studio.enabled: false (the default) if you don't want this.

There is no telemetry, no analytics, no third-party tracking, and no calls to any domain beyond the three above.

Shell/subprocess use. features/briefing/briefing_preflight.py calls osascript for a local macOS notification (best-effort, failure is swallowed). setup_check.py and migrate_to_keychain.py are one-time setup scripts you run yourself. get_cron_health_digest (in tools.py) reads ~/.openclaw/cron/runs/*.jsonl — this is OpenClaw's own cron log directory, used only to summarize this skill's own job results into the daily owner digest; it does not read other skills' data beyond filenames already visible in that shared, host-level directory.

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
• Playwright (only if club_studio.enabled: true) — browser automation dependency for the Club Studio class-schedule scraper, run under a separate system Python interpreter

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