Skip to content
DonnieFiPublic

About

Family coordination bot — Discord + Home Assistant. Household-first, not solo chat.

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Bernie — heraldic guardian gryphon crest

Bernie

The family coordination bot — built for households, not solo chat.
Discord-native. Home Assistant-native. Quiet until it matters.

MIT Python Docker Discord Home Assistant


Most AI assistants are built for one person — a terminal, a DM, a personal workspace. Bernie is built for one household: shared Discord channels, per-person roles (parents vs kids), a morning summary everyone sees, and chores someone actually has to approve.

He is not a generic ChatGPT wrapper. He is family by design.

Home Assistant is the spine. Bernie talks to your HA instance first — presence, lights, sensors, zones, person entities — and from there unlocks the rest of your homelab without wiring up a dozen one-off integrations: Frigate cameras, UniFi clients, vehicle trackers, sleep sensors, network hosts, and anything else you've already modeled in HA. One config block, one token, natural language in #smithy.


Features

  • Home Assistant native — presence, lights, switches, climate, media, and zones via your HA map; Discord + web Home tab + HTTP API share the same tools
  • Family-first Discord — shared channels, parent/kid roles, chore approval, quiet hours
  • Family calendar wall — day, week, and agenda views with person colors, school layers, homework, uniforms, dinners, and groceries
  • OpenAI-compatible API + Swagger — other apps talk to Bernie; he keeps the keys. Interactive docs at :8000/docs. See API
  • Daily morning summary — calendar, weather, who's home — on a schedule
  • Google Calendar — shared schedules, school, homework, and RSVPs with your household's OAuth
  • OpenAI / Codex OAuth — optional ChatGPT/Codex device login with native app-server tool calling
  • Grok OAuth — coming soon; not part of the public setup yet
  • Reminders & automations — per-person DMs or channel pings
  • Meal planning — dinners and groceries on the calendar wall, plus the dedicated family channel
  • Task board — family chores + agent jobs; kids complete, parents approve; web dashboard included
  • Presence & location — who is home / where is someone, from HA trackers
  • Cameras — Frigate snapshots and person alerts (optional)
  • Transit & local services — live buses and garbage day where you configure a feed
  • Weather — live forecast for your coordinates
  • Background helpers — nightly notes, study guides, research (optional local Ollama)
  • Homelab tools — health, network status, optional Langfuse
  • Local & audited — SQLite on disk, secrets gitignored, tool gateway with permissions

Full catalog: Tools · Slash commands · What you can ask

What's in the repo (for beginners)

Path What it is
bot/ The application — Discord, API, workers (what Docker runs)
web/ Family dashboard UI
scripts/ One-off helpers (Google login, tests). Not the main app — see scripts/README.md
docs/ Guides (also buildable as a small website — see below)
config.minimal.example.json Copy to config.json for first run

Mascot image: docs/assets/ATTRIBUTION.md.


Why household-first

Design choice What it means in practice
Household, not user Roles for parents and kids, shared channels, per-person prefs — not a single workspace tied to one identity
Home Assistant as the spine Presence, zones, and devices come first; cameras, transit, and sensors plug in through HA instead of one-off integrations
Bernie holds the keys Your LLM provider (Anthropic, OpenAI, OpenRouter, Ollama, …), HA, and Google credentials live in one place; clients get a single bearer token over an OpenAI-compatible API
Proactive by default Morning summaries and reminders run on a schedule — nobody has to open an app and ask
Built for the homelab Docker, LAN-first, SQLite on disk — runs where your other self-hosted services already live

Bernie doesn't try to be your coding copilot or your second brain. He tries to be the calm adult in the family channel who already checked the calendar, knows who's home, and won't ping the whole house unless it matters.


At a glance

Talk to him Discord (#smithy + channel layout) · web dashboard :8000 · OpenAI-compatible API (/v1/chat/completions) · Swagger (/docs)
Brain Your pick — Anthropic, OpenRouter, optional ChatGPT/Codex OAuth, local Ollama, …
Schedule Google Calendar OAuth → family day/week/agenda wall, school, homework, dinners, and groceries
Home Home Assistant → Frigate, UniFi, sensors, vehicles, sleep
Data SQLite on your host; .env + credentials/ never in git

Model providers (optional Codex OAuth)

Bernie is provider-agnostic — pick any supported route for everyday chat:

  • Anthropic, OpenRouter (including low-cost models such as GPT-5.6 Luna), LiteLLM/proxy, or local Ollama
  • OpenAI via ChatGPT/Codex OAuth (optional) runs through an isolated subscription runner with native Codex app-server tool calling
  • Grok OAuth is coming soon and is not a supported public setup yet

Optional Codex OAuth can pin an OpenRouter fallback for continuity if the subscription needs reauthentication. Activity keeps provider usage separate; subscription attempts also remain visible as provider-labelled Langfuse observations.

Authenticate OpenAI with ChatGPT/Codex OAuth

This uses the official Codex device login and stores OAuth state in the runner's Docker volume—no OpenAI API key or host ~/.codex mount. Generate SUBSCRIPTION_RUNNER_SECRET in .env first.

# From the Bernie repository on the Docker host
openssl rand -hex 32   # save as SUBSCRIPTION_RUNNER_SECRET in .env
docker compose --profile subscriptions up -d --build bernie-subscription-runner

# Open the printed URL in any browser and enter the device code
docker compose --profile subscriptions run --rm \
  --entrypoint codex bernie-subscription-runner login --device-auth

# Verify the volume-backed login
docker compose --profile subscriptions run --rm \
  --entrypoint codex bernie-subscription-runner login status

Then enable the provider: "codex" entry in subscription_models and select its model (for example gpt-5.6-luna) in Bernie's model settings. Re-run the same device-login command whenever provider status reports reauth-required. Never paste the device code or OAuth files into Discord, logs, or credentials/.

For direct Luna setup, Codex OAuth configuration, and readiness details: OpenAI models and Codex OAuth.


Family calendar wall

Open the dashboard at http://<host>:8000, sign in, and choose Calendar in the family navigation:

  • Day — one-day timeline with all-day events and current-time marker.
  • Week — seven-day family wall with person colors and daily event stacks.
  • Agenda — chronological seven-day list for a compact phone-friendly view.
  • People and school layers — filter or dim by family member; parents/admins can show or hide school, homework, and uniform notes.
  • Dinner, groceries, and chores — edit dinner from the day, see homework and chores beside the schedule, and open the shared grocery panel.

Arrow controls move the visible period; Today jumps back to the current date. The selected view and person filter last for the browser session. Calendar events come from the household's Google OAuth calendars; meals and groceries stay in Bernie's database, with optional dinner mirroring to Google Calendar.

Dashboard guide: Web dashboard · calendar setup: Google OAuth.


API — connect your agent

Bernie exposes an OpenAI-compatible chat API on the same port as the dashboard (:8000). Use it to plug in OpenWebUI, scripts, or any client that speaks POST /v1/chat/completions — without scattering LLM, HA, or Google credentials across every app.

He keeps the keys. Your model provider (Anthropic, OpenAI, OpenRouter, Ollama, LiteLLM, …) plus HA and Google live in Bernie's .env / config.json. Callers only need:

  • Base URL: http://<host>:8000 (LAN or VPN; treat like admin access)
  • Bearer token: BERNIE_API_TOKEN (same master token the dashboard API uses)
  • Model id: bernie
Endpoint Auth Purpose
GET /v1/models Authorization: Bearer <token> Lists model bernie
POST /v1/chat/completions Bearer Chat with full Bernie tools (HA, calendar, tasks, …) and family RBAC
POST /api/chat X-Bernie-Token Dashboard-style chat + optional threads
Swagger UI browser on LAN Interactive OpenAPI docs for the full REST surface
OpenAPI JSON — Machine-readable schema

Browse the API: open http://<host>:8000/docs (Swagger UI) or /redoc after the API container is up. Schema is also at /openapi.json. Most routes still need a dashboard login token or BERNIE_API_TOKEN when you try them from Swagger.

Replies go through the same tool gateway and person/role map as Discord — not a stripped “text only” shim.

Minimal example

export BERNIE_URL=http://192.168.1.X:8000   # your API host
export BERNIE_API_TOKEN=…                    # from .env

curl -sS "$BERNIE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $BERNIE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bernie",
    "messages": [{"role": "user", "content": "Who is home right now?"}],
    "stream": false
  }'

OpenWebUI (or similar)

  1. Add a connection / provider with base URL http://<bernie-host>:8000/v1 (or whatever path your client expects for OpenAI-compat).
  2. API key = BERNIE_API_TOKEN.
  3. Model = bernie.
  4. Optional: map OpenWebUI users → family members with openwebui_users / webui_user in config.json so RBAC and memory attach to the right person.

More context: optional services · deploy / CORS.

Exposure: keep :8000 on LAN or VPN. Public internet needs TLS + strong auth — the bearer token is powerful (same class of access as the dashboard).


Quick start

You need: Docker Compose, a Discord server, and one LLM path (API key, local Ollama, or optional Codex OAuth) — about 20 minutes.

1 · Clone & configure

git clone https://github.com/DonnieFi/bernie.git family-bot
cd family-bot

cp .env.example .env
cp config.minimal.example.json config.json
$EDITOR .env          # DISCORD_TOKEN, INTERNAL_POST_SECRET, + one LLM path
$EDITOR config.json   # Discord snowflakes, timezone, family, active_model (match your LLM)

Generate a shared secret for the three-container stack:

openssl rand -hex 32   # paste into INTERNAL_POST_SECRET in .env

Hour-one is provider-agnostic: set whatever credentials match active_model (Anthropic, OpenRouter, Ollama, …).

2 · Discord

Follow docs/discord-onboarding.md — bot token, intents, invite URL, channel IDs.

3 · Google Calendar (recommended)

Each household uses their own Google Cloud OAuth client:

pip install --user google-auth-oauthlib google-api-python-client
python scripts/auth_google.py    # → credentials/token.json

Step-by-step: docs/google-oauth.md

4 · Home Assistant (when you're ready)

Add your HA URL + long-lived token to config.json → home_assistant. Bernie immediately gains presence, device control, and zone landmarks for transit — no separate integration per device.

See Layer by layer § HA.

5 · Run

docker compose -f docker-compose.public.yml up -d --build
docker compose -f docker-compose.public.yml logs -f bernie-discord

Homelab deploys: docker compose up — see docs/deploy.md.

Say hello in your main channel. Bernie should answer.


System requirements

Resource Typical
RAM ~165 MB idle; ~400 MB during tool-heavy turns
Disk ~10 MB SQLite + Docker image
CPU Modest x86_64 or arm64
GPU Not required; nice if Ollama runs on the same box

Ports: :8000 web dashboard + OpenAI-compatible API (/v1/*, /api/*). Outbound: your LLM provider(s) + Google + your LAN (HA, Frigate, LiteLLM, …).


Documentation

Start here: docs/README.md

Guide What it covers
Quickstart First Discord reply in ~30–45 min
Layer by layer Calendar → HA → cameras → email
Discord setup Bot token, intents, channel IDs
Google OAuth Calendar + optional Gmail
OpenAI models and Codex OAuth Luna direct routing and optional ChatGPT/Codex OAuth
Web dashboard Today, family calendar wall, Home, Family, Plan, Activity
What you can ask Natural-language examples
Tools Full tool catalog
FAQ · Troubleshooting When something breaks
Optional integrations OpenWebUI, Frigate, Ollama, …
API OpenAI-compatible /v1 + Swagger at /docs

Optional: browse docs as a website

Markdown in docs/ can be built with MkDocs (beginner-friendly, Python):

pip install -r requirements-docs.txt
mkdocs serve    # http://127.0.0.1:8001

GitHub Pages workflow (.github/workflows/docs.yml) can publish that site when you enable Pages on the repo.

Broken? → Troubleshooting


Discord channels

Channel Purpose
#smithy Main family channel — summaries, chat, presence
#anvil Admin — /model, /reload, eval
#furnace Meal planning
#slag Extended AI chat
#security Frigate / camera alerts
#bellows Chit-chat — bot silent (optional)

Data & privacy

Data Stays where
Chat text Discord + your configured LLM provider per turn
Calendar Google (your account)
HA / cameras / presence LAN — read into prompts, not uploaded
History & routines Local SQLite
Secrets .env + credentials/ — gitignored

No telemetry beacons. Langfuse is opt-in and self-hosted.


Running cost (ballpark)

Depends on model and chatter volume. Example: family of four on a mid-tier cloud chat model often lands around ~$25–30/month; local Ollama for background workers is $0 API. Quiet days: pennies. Switch models anytime (/model, Settings) — Bernie is not locked to one vendor.


License

MIT © 2026 DonnieFi

Copyright and contact are in LICENSE — use GitHub issues (or private vulnerability reporting in SECURITY.md); no maintainer email is published in the tree.

SECURITY.md · CONTRIBUTING.md

About

Family coordination bot — Discord + Home Assistant. Household-first, not solo chat.

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages