# Project pack: KitchenOwl @ cac641c

Facts about **KitchenOwl** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v4.md). Pinned to one version; never changes after publication.

> KitchenOwl is a shopping list that everyone in the house shares. Tap a tile to add milk, and it appears on your partner's phone straight away, even in a shop with bad signal. Keep your recipes, plan the week's meals and add a recipe's ingredients to the list in one go. It can also track shared spending, so you know who paid for what. There are apps for phones, tablets and computers, and you run the server yourself.

## Setup path (checked 2026-11-03)
- **Needs Docker.** Tell the person before any setup work; no light non-Docker route is documented upstream. Docker Desktop on Windows may need a computer restart and an admin-only Windows feature (virtualisation); say so and let the person decide.
- Verdict source: https://raw.githubusercontent.com/TomBursch/kitchenowl/HEAD/README.md
- You may be unable to download source archives or run commands in this session. The person downloads and runs things; if you cannot fetch something, give any changed file in full in chat with its path.

## Version and source
- Repository: https://github.com/TomBursch/kitchenowl
- Pinned commit: `cac641c619963f13134aecb80fadfb81f0c9249b`. Use exactly this version.
- Zip the person can download in a browser: https://github.com/TomBursch/kitchenowl/archive/cac641c619963f13134aecb80fadfb81f0c9249b.zip
- Fresh checkout (only if you have a shell and git): use the commands below in an empty folder. If this exact source is already checked out, keep your branch and use the development command; do not clone again or reset local changes.
- Official docs: https://docs.kitchenowl.org
- Licence: **AGPL-3.0-only**. Free to use and change. If you run a changed version that other people use over the internet (not just your own household), you must offer them your source code under the same licence. Private family use has no extra obligations.

## Commands from the pinned source
- Developer commands (they may use Docker):

  ```sh
  git clone https://github.com/TomBursch/kitchenowl bespoke-kitchenowl
  cd bespoke-kitchenowl
  git checkout --detach cac641c619963f13134aecb80fadfb81f0c9249b
  # Prepare development requirements and local configuration first.
  # Setup notes: API on :5000; then in kitchenowl/: flutter packages get && touch .env && flutter run
  cd backend && uv sync && uv run flask db upgrade && uv run wsgi.py
  ```

- Separate trial of the current upstream release (not your changes; sample data and a separate data directory only):

  ```sh
  docker volume create kitchenowl_data && docker run -d -p 8080:8080 -e "JWT_SECRET_KEY=$(openssl rand -hex 32)" -v kitchenowl_data:/data tombursch/kitchenowl:latest # then open http://localhost:8080 and create the first (admin) account, or connect the phone app to this address.
  ```
- Tools these commands use: Docker (the all-in-one image), or separate kitchenowl-web and kitchenowl-backend images with docker compose, For development, Python with uv for the backend and the Flutter SDK for the app
- Develop: `cd backend && uv sync && uv run flask db upgrade && uv run wsgi.py   # API on :5000; then in kitchenowl/: flutter packages get && touch .env && flutter run`
- Test: `cd backend && uv run pytest   # app: cd kitchenowl && flutter test`
- Check/lint: `cd kitchenowl && flutter analyze   # backend uses pre-commit hooks (uv run pre-commit install)`
- Stack: python, dart (Flask, SQLAlchemy, Alembic (Flask-Migrate), Socket.IO, Flutter, flutter_bloc). Difficulty for a non-developer with an AI: **moderate**. Two parts: a Flask backend (backend/) and a Flutter app (kitchenowl/) that is the website, the phone apps and the desktop apps at once. Server behaviour is set with environment variables; household options are in the app. Code changes often touch both a Flask controller and a Flutter page, and the Flutter toolchain is a large install.
Personal data: **yes**. Stored in: SQLite database and uploaded photos in the kitchenowl_data volume (/data); PostgreSQL optional. Secrets are entered by the person, never in chat.

---
Later, only when a step needs it: [reference.md](https://handoff.bespokeai.software/p/kitchenowl/cac641c/r3/reference.md) (customisation points, must-keep-working, data and costs, coding conventions) · [hosting.md](https://handoff.bespokeai.software/p/kitchenowl/cac641c/r3/hosting.md) (long-term hosting; hosts are paid third parties) · [bespoke.yaml](https://handoff.bespokeai.software/p/kitchenowl/cac641c/r3/bespoke.yaml) · [SKILL.md](https://handoff.bespokeai.software/p/kitchenowl/cac641c/r3/SKILL.md)