# Project pack: Beaver Habit Tracker @ 332a453

Facts about **Beaver Habit Tracker** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Beaver Habit Tracker is a simple checklist for the things you want to do regularly, like a walk, reading or calling your mum. Each habit has a row of days you tick, plus a calendar and heatmap that show how you've been doing. There are no targets or scores, just a record. It runs on your own computer or server and works well on a phone.

## Version and source
- Repository: https://github.com/daya0576/beaverhabits
- Pinned commit: `332a45336158a4a50885b4d3bc6146cd27528fc9`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/daya0576/beaverhabits/archive/332a45336158a4a50885b4d3bc6146cd27528fc9.zip
- Official docs: https://github.com/daya0576/beaverhabits/wiki
- Live demo: https://beaverhabits.com/demo. Official demo on the author's hosted service. Nothing you enter there is private.
- Licence: **BSD-3-Clause**. Very permissive. You can use, change and share it, even commercially. If you pass on copies, keep the copyright notice and licence text, and don't use the author's name to promote your version.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/daya0576/beaverhabits bespoke-beaverhabits
  cd bespoke-beaverhabits
  git checkout --detach 332a45336158a4a50885b4d3bc6146cd27528fc9
  # Prepare development requirements and local configuration first.
  # Setup notes: app on http://localhost:9001 with auto-reload
  uv venv && uv sync && ./start.sh dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  mkdir -p beaver && docker run -d --name beaverhabits -u $(id -u):$(id -g) -e HABITS_STORAGE=USER_DISK -v ./beaver/:/app/.user/ -p 8080:8080 daya0576/beaverhabits:latest # then open http://localhost:8080 and register your account
  ```

- Needs: Docker, or for development Python 3.12+ and uv
- Develop: `uv venv && uv sync && ./start.sh dev   # app on http://localhost:9001 with auto-reload`
- Test: `uv sync --group fly && DATABASE_URL="sqlite+aiosqlite:///:memory:" HABITS_STORAGE="USER_DISK" uv run pytest`
- Stack: python (FastAPI, NiceGUI, Quasar, SQLAlchemy, fastapi-users). Difficulty for a non-developer with an AI: **easy**. A small, single-language project (about 60 Python files). The screens are written in Python with NiceGUI, so there is no separate JavaScript build. Display options are environment variables and per-user custom CSS. Code changes live in beaverhabits/frontend/ (screens) and beaverhabits/storage/ (data).

## The project's own AI instructions
Read these in the repository before changing code: `.github/copilot-instructions.md`.

## Customisation points (settings → extend → code)
- **display-options** [settings]: How many days show, which day starts the week, streaks and counts on the main page, tag filters. → `Environment variables listed in beaverhabits/configs.py (INDEX_HABIT_DATE_COLUMNS, FIRST_DAY_OF_WEEK, INDEX_SHOW_HABIT_STREAK…)`
- **custom-css** [settings]: Change colours, fonts and sizes for your account with a few lines of CSS. No rebuild. → `Menu → Settings → Custom CSS (beaverhabits/frontend/settings_page.py)`
- **completion-status** [settings]: Extra answers beyond yes/no, such as "skip" or "sick", each with its own colour. → `Menu → Completion Status (beaverhabits/frontend/chip_sets_page.py)`
- **accounts-and-login** [settings]: One-person mode without a login screen on a home network, or invite-only accounts for a family. → `TRUSTED_LOCAL_EMAIL, REQUIRE_ADMIN_FOR_REGISTRATION, MAX_USER_COUNT (beaverhabits/configs.py)`
- **rest-api** [extend]: Tick habits from a phone shortcut, Home Assistant, a Stream Deck or a script. → `REST API under /api/v1 (beaverhabits/routes/api.py), tokens from Menu → Tools → API Tokens, docs at /docs`
- **import-export** [extend]: Move habits in and out as JSON or CSV, and send daily backups to Telegram. → `Export and Import pages (beaverhabits/frontend/export_page.py, import_page.py)`
- **screens** [code]: Change or add screens, such as a weekly summary or a bigger tick button. → `beaverhabits/frontend/ (index_page.py, habit_page.py, stats_page.py, components.py)`
- **storage** [code]: New information on a habit, such as a target time or a category colour. → `beaverhabits/storage/ (storage.py defines the data; dict.py, user_db.py, user_file.py implement it)`

## Must keep working
- Existing habit history. Export a JSON backup before any upgrade or code change.
- The three storage modes (session, user disk, database) must keep reading the same data.
- The REST API under /api/v1. Phone shortcuts, Home Assistant and the iOS app depend on it.
- Each user only ever sees their own habits.

## Staying updatable
Environment variables, custom CSS, completion statuses and the API cover most personal tweaks without a fork. The project is maintained by one author and follows the conventions in .github/copilot-instructions.md; keep code changes small and in your own copy unless they would help everyone.

## Data, costs and safety
- Personal data: **yes**. Stored in: The /app/.user folder in the container: one JSON file per user (HABITS_STORAGE=USER_DISK) or habits.db (SQLite). PostgreSQL is possible through DATABASE_URL. Habits and notes can say a lot about your health and routines. Back up the mounted folder (./beaver), and use the Export page to download a JSON copy before upgrades or code changes.
- Service: Telegram bot (optional, free): Optional daily backup of your habits as a JSON file sent to a Telegram chat (set up on the Export page).
- Service: Email (SMTP) (optional, free with most providers): Password-reset emails.
- Service: Google sign-in (One Tap) (optional, free): Log in with a Google account instead of a password.
- Setting `HABITS_STORAGE`: Where habits are kept. USER_DISK saves a JSON file per user; DATABASE (the default) uses one SQLite database.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Database address if you use PostgreSQL instead of the built-in SQLite. Can contain a password.
- Setting `TRUSTED_LOCAL_EMAIL`: Skips the login screen and signs everyone in as this email. Only for a private home network.
- Setting `JWT_SECRET` (**secret**: the person enters it themselves, never in chat): Secret that signs login sessions. The default is the word "SECRET"; set a long random value on any shared server.
- Setting `NICEGUI_STORAGE_SECRET` (**secret**: the person enters it themselves, never in chat): Secret for browser session storage. The default is "dev"; set a long random value.
- Setting `FIRST_DAY_OF_WEEK`: 0 for Monday (default) to 6 for Sunday.
- Setting `INDEX_HABIT_DATE_COLUMNS`: How many days show on the main page (default 5).
- Setting `INDEX_SHOW_HABIT_STREAK`: Show each habit's current streak on the main page.
- Setting `TIME_ZONE`: Force a time zone such as Europe/London for everyone (otherwise taken from the browser).
- Setting `MAX_USER_COUNT`: Limit how many accounts can be registered (-1 means no limit).
- Setting `REQUIRE_ADMIN_FOR_REGISTRATION`: Only the admin (ADMIN_EMAIL) can create new accounts.
- Setting `ADMIN_EMAIL`: The admin account's email. Needed when REQUIRE_ADMIN_FOR_REGISTRATION is on.
- Setting `ENABLE_DAILY_BACKUP`: Turn on the scheduled backup that sends each user's habits to their Telegram chat.
- Set JWT_SECRET and NICEGUI_STORAGE_SECRET to long random values. The defaults are public and weak.
- TRUSTED_LOCAL_EMAIL turns off the login screen. Never use it on a server reachable from the internet.
- On an internet-facing server, use HTTPS through a reverse proxy and limit sign-ups (REQUIRE_ADMIN_FOR_REGISTRATION or MAX_USER_COUNT).
- API tokens give full access to your habits. Treat them like passwords and never paste them into an AI chat.

---

# Customising Beaver Habit Tracker

Beaver Habit Tracker is small and written entirely in Python, so it is one of the gentler projects to change. **Still, most personal tweaks are settings.** Try levels 1 and 2 first.

## Level 1: Settings (no code)
- **What the main page shows:** environment variables on the container, then restart it. All options and defaults are in `beaverhabits/configs.py`:
  - `INDEX_HABIT_DATE_COLUMNS` (how many days), `INDEX_HABIT_DATE_REVERSE` (newest day first or last)
  - `FIRST_DAY_OF_WEEK` (0 = Monday … 6 = Sunday), `TIME_ZONE` (e.g. `Europe/London`)
  - `INDEX_SHOW_HABIT_STREAK`, `INDEX_SHOW_HABIT_COUNT`, `ENABLE_TAG_FILTERS`, `TAG_SELECTION_MODE`
- **Colours and sizes:** Menu → Settings → *Custom CSS*. Saved per account and applied straight away.
- **Statuses beyond yes/no:** Menu → *Completion Status*. Add options such as `skip` or `ill`, each with a colour.
- **Order of habits:** Menu → Order (by name, by category or by hand).
- **Who can log in:**
  - `TRUSTED_LOCAL_EMAIL` skips the login screen (home network only).
  - `REQUIRE_ADMIN_FOR_REGISTRATION` with `ADMIN_EMAIL` makes accounts invite-only.
  - `MAX_USER_COUNT` caps the number of accounts.

## Level 2: Extend (no fork)
- **REST API** under `/api/v1` (`beaverhabits/routes/api.py`). Make a token in Menu → Tools → API Tokens. The interactive docs are at `/docs` on your server. Good for phone shortcuts, Home Assistant, a Stream Deck or a little script.
- **Import and export:** the Export page downloads JSON; the Import page reads JSON or CSV.
- **Telegram backup:** the Export page can send a daily JSON backup to a Telegram chat. Set `ENABLE_DAILY_BACKUP=true` on the server.
- The upstream wiki lists community add-ons (CalDAV bridge, iOS app, HabitDeck).

## Level 3: Code
Read upstream `.github/copilot-instructions.md` first. It is short.

| Change | Where |
|---|---|
| Main habit list | `beaverhabits/frontend/index_page.py`, shared pieces in `components.py` |
| One habit's calendar and heatmap | `beaverhabits/frontend/habit_page.py`, `streaks.py` |
| Statistics page | `beaverhabits/frontend/stats_page.py` |
| Menu items | `beaverhabits/frontend/menu.py` |
| New page | Add a page function in `beaverhabits/frontend/`, then register it in `beaverhabits/routes/routes.py` (both `/gui/...` and, if wanted, `/demo/...`) |
| What a habit stores | `beaverhabits/storage/storage.py` (interfaces), `dict.py` (JSON shape), `user_db.py`, `user_file.py` |
| API endpoints | `beaverhabits/routes/api.py` |
| New setting | `beaverhabits/configs.py` |

## Running locally
- **Just use it:** `docker run -d -u $(id -u):$(id -g) -e HABITS_STORAGE=USER_DISK -v ./beaver/:/app/.user/ -p 8080:8080 daya0576/beaverhabits:latest`, then open http://localhost:8080.
- **Develop:**
  1. Install uv.
  2. Run `uv venv && uv sync`.
  3. Start with `./start.sh dev`.
  4. Open http://localhost:9001. It reloads when you save a file.
- **Check:** `uv sync --group fly`, then `DATABASE_URL="sqlite+aiosqlite:///:memory:" HABITS_STORAGE="USER_DISK" uv run pytest`.

## Pitfalls
- The container runs as an ordinary user. If the mounted `beaver` folder belongs to someone else, it can't save. Match the `-u` user to the folder's owner.
- Changes to the data shape must work for all three storage modes (session, JSON file and database).
- Export a JSON backup before changing code. Habit history can't be rebuilt.
- The `statics/astro` folder is a separate landing-page project (a git submodule). You don't need it to run the app.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/beaverhabits/332a453/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/beaverhabits/332a453/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/beaverhabits/332a453/r2/SKILL.md)