# Project pack: Fava @ b89d5f5

Facts about **Fava** 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.

> Fava is the browser front end for Beancount, a plain-text accounting system. You keep your money records in a text file, and Fava turns it into balance sheets, income statements, budgets, charts and a searchable journal. Your books are plain files you can version and keep forever.

## Version and source
- Repository: https://github.com/beancount/fava
- Pinned commit: `b89d5f5e58bad7d8c84523946d4c41dd94f3765c`. 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/beancount/fava/archive/b89d5f5e58bad7d8c84523946d4c41dd94f3765c.zip
- Official docs: https://beancount.github.io/fava/usage.html
- Live demo: https://fava.pythonanywhere.com/example-with-budgets/income_statement/. Read-only example ledger. No real data.
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

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

  ```sh
  git clone https://github.com/beancount/fava bespoke-fava
  cd bespoke-fava
  git checkout --detach b89d5f5e58bad7d8c84523946d4c41dd94f3765c
  # Prepare development requirements and local configuration first.
  python3 -m venv .venv
  . .venv/bin/activate
  pip install -e .
  make -C frontend install
  fava src/fava/help/example.beancount
  ```

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
  pip install fava
  fava path/to/your-ledger.beancount
  # then open http://localhost:5000
  ```

- Needs: Python 3.10+; Node for front-end development
- Develop: `fava src/fava/help/example.beancount`
- Test: `make test`
- Check/lint: `make lint`
- Stack: python, typescript, svelte (Flask, Svelte, Beancount). Difficulty for a non-developer with an AI: **moderate**. A Python web app with a Svelte front end. Most personal changes are Beancount settings, reports and Fava extensions, not forks. Learning Beancount itself is the bigger hill.

## Customisation points (settings → extend → code)
- **fava-options** [settings]: Which reports show, default filters, currencies and number formats. → `"option custom 'fava-option' lines in your .beancount file"`
- **budgets-and-queries** [settings]: Monthly budgets and your own reports. → `custom 'budget' directives and saved BQL queries`
- **extensions** [extend]: Add pages, charts and import helpers written in Python. → `Fava extension modules (src/fava/ext)`
- **importers** [extend]: Turn your bank's CSV into Beancount entries. → `Beancount importers (beangulp) in your own repo`
- **web-ui** [code]: New reports and charts. → `frontend/src and src/fava/templates`

## Must keep working
- Never rewrite a user's ledger file except through Fava's own editor.
- Balance assertions and the validation that Fava runs on load.
- Support for existing Beancount syntax.

## Staying updatable
Write extensions and importers in your own folder, outside the Fava source. Then upgrading is simply pip install --upgrade.

## Data, costs and safety
- Personal data: **yes**. Stored in: Your Beancount ledger files and any attached documents on disk. The ledger is the single source of truth. Keep it in Git and back it up.
- Your ledger shows everything about your money. Run Fava on your own machine or behind a login.
- Fava has no built-in login. Do not expose it to the internet without a reverse proxy that requires one.

---

# Customising Fava

Most of what you want from Fava belongs in your own ledger, extension or importer, outside this repository.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Your ledger and options | your .beancount files (not in this repo) |
| Server and API | src/fava/core/ and src/fava/json_api.py |
| Pages and templates | src/fava/templates/ |
| Front end (Svelte) | frontend/src/ |
| Extensions | src/fava/ext/ (see the example extensions in contrib/) |
| Example data | src/fava/help/example.beancount |

## Use the gentlest change first

1. **Settings (no code):** `fava-option` lines, budgets and saved queries in the ledger.
2. **Extend:** a Python extension or an importer.
3. **Code:** the Svelte front end and the Python core.

## Recipes

- **Importer:** subclass the Beancount importer base class, test it with a few sample rows, then run it from `bean-extract`.
- **Extension:** create a class with a `report_title` and a template, register it with an `option custom "fava-extension"` line.

## Running and checking your changes

- `make test` runs front-end and Python tests.
- Load the example ledger and click through each report.
- Run `bean-check` on any ledger you edit.

## Pitfalls

- Use a copy of your ledger while developing.
- Fava reads files directly. A bad importer can create wrong balances, so use balance assertions.

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