Skip to content
Back to search

familywell

The family organizer for the people you live with: shopping lists, to-dos, calendar, spending, projects, recipes and more. Self-hostable, modular Laravel + React PWA with an MCP server for AI assistants. Free for personal use.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bvdr/familywell with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bvdr/familywell'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bvdr--familywell/badge.svg)](/listings/bvdr--familywell)

HTML

<a href="/listings/bvdr--familywell"><img src="/api/listings/bvdr--familywell/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**Prerequisites:** PHP 8.2+, [Composer](https://getcomposer.org), Node 22+, and npm. No database server needed, local defaults to SQLite.

git clone https://github.com/bvdr/familywell.git
cd familywell

composer install
npm install

cp .env.example .env
php artisan key:generate
touch database/database.sqlite

php artisan migrate          # core tables
php artisan modules:migrate  # module tables

composer dev                 # serves the app + queue + logs + Vite together

Open http://localhost:8000, register an account (the first user creates a family), then enable a module from **Settings → Modules**.

`composer dev` runs the PHP server, the queue worker, the log tailer, and the Vite dev server concurrently. Run `npm run build` for a production asset build.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 182 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # FamilyWell
  2. <!-- Homer, the mascot: rendered from the character sheet (familywell-site: mascot/homer, tools/readme-greeting.mjs). Dark variant has light outlines for GitHub's dark theme. -->
  3. <p align="center">
  4. <picture>
  5. <source media="(prefers-color-scheme: dark)" srcset="docs/images/homer-hello-dark.webp">
  6. <img src="docs/images/homer-hello-light.webp" width="200" alt="Homer, the FamilyWell mascot, sways, jumps, then lifts his roof like a hat to say hello">
  7. </picture>
  8. </p>
  9. **The family organizer for the people you live with.** Shared shopping lists, to-dos, a family calendar, spending, projects, recipes, the car and more, in one installable app. A small, stable core with self-contained **modules** you switch on per family, so each household only sees what it uses.
  10. Self-host it for your own family, or use the hosted version at **[familywell.co](https://familywell.co)** (there's a one-click live demo).
  11. [![License: PolyForm Noncommercial 1.0.0](https://img.shields.io/badge/license-PolyForm%20Noncommercial-blue.svg)](LICENSE)
  12. <p align="center">
  13. <img src="docs/screenshots/phone-dashboard.png" width="200" alt="Home screen: this month's spending, what's happening now and next, birthdays, and today's to-dos">
  14. <img src="docs/screenshots/phone-shopping.png" width="200" alt="A shared grocery list grouped by aisle">
  15. <img src="docs/screenshots/phone-project.png" width="200" alt="A family project with progress and tasks">
  16. <img src="docs/screenshots/phone-recipe.png" width="200" alt="A recipe with a servings calculator">
  17. </p>
  18. <p align="center">
  19. <img src="docs/screenshots/phone-spending.png" width="200" alt="Spending: this month's total and the latest expenses">
  20. <img src="docs/screenshots/phone-vehicle.png" width="200" alt="A family car with maintenance due, mileage, fuel, tyres and documents">
  21. </p>
  22. <p align="center">
  23. <img src="docs/screenshots/desktop-calendar-month.png" width="820" alt="Family calendar, month view, with a trip, recurring swim practice and to-do due dates">
  24. </p>
  25. > **Source-available, not open source.** FamilyWell is free for **personal, noncommercial use**: run it for your own family, change it, learn from it. Commercial use and reselling are not allowed. See [License](#license).
  26. ---
  27. ## What you get
  28. - **Families, not just accounts.** Invite the people you live with; everyone shares the same data, with roles (admin / member).
  29. - **Modules you switch on per family** (Settings → Modules). Bundled:
  30. - **[Shopping](modules/shopping)**: several shared lists, grouped by aisle per shop, a "shopping mode", voice and paste input.
  31. - **[Tasks](modules/tasks)**: shared to-do lists with sub-tasks, due dates and assignees, plus [important](modules/important_todos) and [recurring](modules/recurring_todos) to-dos.
  32. - **[Calendar](modules/calendar)**: month and timeline views, repeating events, people and to-dos on events. Task due dates, birthdays, car due dates and project starts show up on their own. Includes a private subscribe link for Google or Apple Calendar.
  33. - **[Spending](modules/spending)**: quick-add expenses, categories, shared trackers with automatic "who owes whom", multi-currency, receipt photos and optional AI receipt scanning.
  34. - **[Projects](modules/projects)**: the bigger things a family works on, with tasks, progress and linked shopping lists.
  35. - **[Recipes](modules/recipes)**: family recipes with a calculator (scale by servings, total amount or what you have) and add-to-shopping.
  36. - **[Notes](modules/notes)**, **[Contacts](modules/contacts)**, **[Birthdays](modules/birthdays)**, **[Inventory](modules/inventory)** (what's in the house and what's running low) and **[Vehicles](modules/vehicles)** (mileage, maintenance, documents).
  37. - **A home screen that brings it together**: this month's spending, what's on now and next, birthdays, and what's due today and this week.
  38. - **Granular sharing**: anything shareable can be *family-wide*, *invited-only* or *private*, with per-person roles and read-only public links.
  39. - **Works with AI assistants**: a built-in [MCP server](docs/mcp.md) lets Claude, ChatGPT and other MCP clients read and update your family's lists, calendar and more, with per-module permissions you pick when you connect. Interactive widgets render right in the chat.
  40. - **Realtime and installable**: changes appear live for everyone (Laravel Reverb), and it installs to your home screen as a PWA.
  41. - **Two languages so far**: English and Romanian, per person.
  42. <p align="center">
  43. <img src="docs/screenshots/desktop-calendar-timeline.png" width="820" alt="Family calendar, timeline view">
  44. </p>
  45. ## Tech stack
  46. | Layer | Choice |
  47. |---|---|
  48. | Backend | PHP 8.2+, Laravel 12, Laravel Octane (FrankenPHP) |
  49. | Frontend | Inertia.js 2, React 19, TypeScript, Tailwind CSS v4 |
  50. | Realtime | Laravel Reverb (WebSockets) |
  51. | Database | PostgreSQL (production) · SQLite (local, zero-config) |
  52. | Storage | Any S3-compatible bucket (Cloudflare R2 in the cloud build) |
  53. | Build | Vite |
  54. One Docker image runs the same way self-hosted and in the cloud.
  55. ---
  56. ## Quick start (local development)
  57. **Prerequisites:** PHP 8.2+, [Composer](https://getcomposer.org), Node 22+, and npm. No database server needed, local defaults to SQLite.
  58. ```bash
  59. git clone https://github.com/bvdr/familywell.git
  60. cd familywell
  61. composer install
  62. npm install
  63. cp .env.example .env
  64. php artisan key:generate
  65. touch database/database.sqlite
  66. php artisan migrate # core tables
  67. php artisan modules:migrate # module tables
  68. composer dev # serves the app + queue + logs + Vite together
  69. ```
  70. Open http://localhost:8000, register an account (the first user creates a family), then enable a module from **Settings → Modules**.
  71. `composer dev` runs the PHP server, the queue worker, the log tailer, and the Vite dev server concurrently. Run `npm run build` for a production asset build.
  72. ---
  73. ## Self-hosting
  74. The whole app is a single image with a `docker compose` stack (app + Postgres + Redis, optional Reverb for realtime). Only Docker is needed on the server. In an empty folder:
  75. ```bash
  76. curl -fsSL https://raw.githubusercontent.com/bvdr/familywell/main/docker-compose.yml -o docker-compose.yml && docker compose up -d
  77. ```
  78. Then open **http://localhost:8000** and sign up. The container generates its own encryption key and sets up the database on first start. Until mail is configured, read your sign-in code with `docker compose logs app | grep "FamilyWell code"`.
  79. Upgrade with `docker compose pull && docker compose up -d`. The image is `ghcr.io/bvdr/familywell:stable` (x86-64; on ARM, clone and run `docker compose up -d --build`). See **[docs/self-hosting.md](docs/self-hosting.md)** for the full guide: going public, backups, mail, storage and Reverb.
  80. ### Public demo account (optional)
  81. A "Try the live demo" button appears on the login page once a demo family exists. Visitors are signed
  82. in as its owner with one click (`/demo`), can change anything, and the family is wiped and re-seeded
  83. at the top of every hour by the scheduler (`demo:reset`).
  84. ```bash
  85. php artisan db:seed --class=DemoSeeder --force # once: creates the demo family (flagged is_demo)
  86. php artisan demo:reset # any time: wipe + re-seed it (what the scheduler runs)
  87. ```
  88. The reset locates the family **only** by the `families.is_demo` flag and refuses to run unless exactly
  89. one family carries it, so it can never touch a real family.
  90. ---
  91. ## Configuration
  92. Everything is configured through environment variables in `.env`. See **[docs/configuration.md](docs/configuration.md)** for the complete reference. Highlights:
  93. ### AI receipt scanning (optional)
  94. When a Google Gemini API key is present, spends gain a **Scan receipt** action: snap a photo and the amount, currency, date, category, shop, and a note are read from it and pre-filled for you to review and save. It costs roughly **$0.001 per scan** and reads rotated, low-quality, multilingual receipts.
  95. The feature is **entirely gated on the key**, without it there is no button and the endpoint returns 404. To enable it, get a free key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey) and set:
  96. ```dotenv
  97. GEMINI_API_KEY=your-key-here
  98. ```
  99. ### AI categorisation (optional)
  100. With a [TypeSafe](https://typesafe.ai) key, shopping items added into the catch-all **Other** aisle are sorted into the shop's best-fit aisle (Dairy, Produce, Plumbing, ...) right after they're saved, expenses saved into "Other" get a category the same way, and Spending settings has a one-tap **Sort "Other" with AI** for the backlog, with a progress bar:
  101. ```dotenv
  102. TYPESAFE_API_KEY=your-key-here
  103. ```
  104. No secrets are ever committed; `.env` and every credential file are git-ignored.
  105. ---
  106. ## Modules
  107. FamilyWell's features live in `modules/`. Each module is a self-contained folder with its own routes, controllers, models, migrations, and (optionally) a frontend bundle, registered through a service provider and a `module.json` manifest. Every feature listed above is a module; `modules/important_todos` is a small example to start from.
  108. To learn how the module system works and how to build your own, see **[docs/modules.md](docs/modules.md)**.
  109. ## Project structure
  110. ```
  111. app/ Core Laravel application (families, auth, sharing, modules)
  112. modules/ Self-contained feature modules (shopping, tasks, calendar, spending, ...)
  113. resources/js/ React + Inertia frontend (pages, components, layouts)
  114. routes/ Core web routes
  115. docs/ Documentation and design notes
  116. .do/ DigitalOcean App Platform deploy config (non-secret)
  117. ```
  118. ## Contributing
  119. Contributions are welcome: bug fixes, new modules, translations, docs. Start with **[CONTRIBUTING.md](CONTRIBUTING.md)** for the workflow, conventions, and the terms your contribution is accepted under.
  120. ## License
  121. FamilyWell is licensed under the **[PolyForm Noncommercial License 1.0.0](LICENSE)**. It's source-available, not open source:
  122. - **Allowed:** personal and family use, self-hosting for your own household, studying, modifying and sharing the code for noncommercial purposes. Noncommercial organisations (a charity, a school, a public research group) may use it too, as the license defines.
  123. - **Not allowed:** any commercial use, including selling or reselling FamilyWell or a modified version, offering it as a paid or hosted service, or using it inside a business.
  124. Any copy or modified version must keep the license and its `Required Notice` line. For commercial licensing, contact the maintainer through [familywell.co](https://familywell.co).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.