Family Assistant
The Family Assistant is a h@llo.ai assistant that plans the family's day. It reads the documents in folders you choose (school letters, photos of flyers, doctor's notes, lists), your calendars and your reminders, and answers questions like:
- "Was steht heute an?" / "What's on today?"
- "What does Emma need for tomorrow?"
- "Welche Fristen laufen diese Woche ab?"
- "When is the next dentist appointment?"
When a document is added, the assistant looks for upcoming dates, deadlines and preparation instructions such as "bitte Brotzeit mitgeben" or "return the form by Friday". It keeps each one with the exact quote it came from, so answers can name their source. It never invents packing lists or dates. Anything it can't back up with a quote from the document goes to a review list instead of being treated as a fact.
Setting it up
The Family Assistant requires macOS 14 or later. In BetterTouchTool's configuration, go to h@llo.ai / AI Assistants, add a new item and choose h@llo.ai - Family Assistant as its type. Then click Set Up Family Assistant…. The wizard takes a few minutes:
- Where the AI runs. Pick Use my AI connection (recommended) with one of your existing connections or a new one, or Keep everything on this Mac. For the private mode, use a model server on this Mac (LM Studio, Ollama, …) with a capable model; Apple Intelligence only works as a basic fallback and misses more dates. You choose this before any file name or document is read.
- Family. Add names and nicknames ("Emmi", "Kind 1"), which help the assistant tell who a letter is about.
- Folders. Click Create "Family" in iCloud Drive, or choose existing folders (Dropbox and other cloud folders work too), and drag folders onto the list to add more. Give each folder a label and a one-sentence description, for example "Letters from Emma's school, class 4b". The assistant reads these descriptions. Suggest writes a description for you from the folder name and a few file names, using only an AI model that folder is allowed to use. About assigns everything in a folder to one person; folders named after a family member (e.g.
Kinder/Max) are assigned automatically. - Calendars & reminders. Assign calendars and reminder lists to a person or to Shared (family); titles that contain a name are suggested automatically. Only assigned calendars are read. Choose where new entries may be added. Without a target, nothing is ever added.
- Daily routine. Turn on the morning brief, the evening prep and the weekly overview.
Indexing runs in the background, and you can start asking right away. The first folder you add is the primary folder. It holds Household.md, the Inbox folder for notes and .btt/household.json, which lets a second Mac import the family setup.
For iCloud Drive or Dropbox folders, right-click the folder in Finder and choose Keep Downloaded. Files that exist only in the cloud are downloaded when needed, two at a time. Until they arrive, answers mention that some files are still downloading.
Household.md
The setup creates a Household.md in the primary folder. Write routines there, one per line:
## Routines
- Tuesdays 15:00–16:00 swimming (Emma): towel, goggles, 2 € for the locker
- Thursdays: Lukas' Kita closes at 14:00
Routines appear on the agenda on the right weekdays. When your calendar has a matching entry, such as "Schwimmen" in Emma's calendar, the preparation list is attached to that entry.
Asking
Open the Family Assistant from the launcher, the menu bar Ask… field (choose it as the assistant), its item in the AI section (Open Family Assistant), or any trigger with the action Show Customizable AI Assistant set to "Family Assistant". Answers are grouped by person, list what to bring or do as a checklist, and cite the document, for example "from Elternbrief Wandertag.pdf".
The assistant tells you when something could not be checked: files still downloading, documents not yet analyzed, missing calendar access, or folders hidden from a remote model by privacy settings. It never presents an incomplete check as "nothing to do".
It can also save notes ("remember that Emma needs 5 € on Friday" becomes a Markdown file in Inbox/), mark items done, and add an item to the calendar when you ask. Changes always show an approval card first, because the Family Assistant starts in Ask Before Changes mode with memory turned off.
Review
Review Found Dates & Deadlines… (on the Family Assistant item in the AI section) lists:
- Needs your review: facts without clear evidence (for example a date that isn't in the quoted text, a relative date like "next Tuesday", or an unclear person), corrections that could not be matched, items whose source file disappeared, and calendar entries that no longer match their source.
- Upcoming: supported items with Add to Calendar…, Edit…, Mark Done and Dismiss.
When a school sends a corrected or canceled letter, the existing item moves to the new date or is marked canceled instead of being duplicated. If the activity is already in your calendar, you are asked before the calendar entry is updated or removed. Your own edits and "done" states are kept.
Briefs and notifications
- Morning brief (weekdays 6:45), evening prep (19:30) and weekly overview (Sundays 18:00) run as scheduled automations in read-only mode and post a notification. Change their times under h@llo.ai chat → ⋯ → Automations….
- The evening prep stays silent only when every source could be checked and nothing is due or waiting for review.
- Notify me when a new document contains dates (Settings → Routines) posts a notification for new letters. For a single item with a selected calendar, it offers Add to Calendar, which adds exactly what the notification shows. If anything changed in the meantime, you are asked to review first.
Privacy
| Setting | What reaches an AI model |
|---|---|
| Keep everything on this Mac | Nothing leaves your Mac. A model server on this Mac (address localhost) that you chose for this mode, or Apple's on-device model as a basic fallback, reads documents and answers questions. The assistant refuses to work with any other model in this mode. |
| Use my AI connection | Document text the assistant looks at, extracted dates, family names and calendar entries go to the selected provider. |
| Folder: On-device only | That folder's content, file names and description never reach a remote model, including in search results, the agenda and context. |
Extracted text and the search index are stored only in ~/Library/Application Support/BetterTouchTool/AI/Library/. Your folders are never changed, except for Household.md, notes in Inbox/ and .btt/household.json in the primary folder. Overview → Remove Family Assistant… deletes the index and settings.
Command-line agents (Claude Code, Codex, OpenCode) can answer questions, but they are never used to read documents. With such a connection, documents are analyzed with Apple Intelligence when it's available.
External MCP clients cannot see family data unless you turn on Allow external tools (MCP clients) to read family data in Privacy & AI. Even then, access is read-only and folders marked on-device only stay hidden.
Email (optional)
In Privacy & AI, Include one Mail mailbox reads new messages from one Mail.app mailbox, such as "Familie", every 30 minutes while Mail is open. A Mail rule that moves school emails into that mailbox works well. Messages, including their PDF attachments, are stored only on this Mac. Optionally, PDF attachments can also be saved into the primary folder's Inbox/Mail. macOS asks once whether BetterTouchTool may control Mail. Gmail users can instead add a Gmail MCP server to the assistant.
Supported files
Text and Markdown, PDF (scanned pages are read with text recognition), photos and screenshots (HEIC, JPEG, PNG), RTF, Word (.docx, .doc), OpenDocument, HTML, email (.eml), calendar invitations (.ics, including weekly repeats and cancellations), web links, and Pages/Numbers/Keynote documents that contain a preview PDF. Large PDFs are read up to 60 pages; the rest is reported as not read.
Troubleshooting
- "N document(s) wait for a permitted AI model to find dates." The folder is on-device only but Apple Intelligence is not available, or no usable API connection is selected. Search still works.
- A folder shows as not available. It was disconnected or access was revoked. The last known state stays visible, marked as possibly outdated, until the folder is back.
- Folders, family, calendars and privacy can be changed with Folders, Family, Calendars & Privacy… on the Family Assistant item in the AI section.