AI finance coach

A private, self-hosted coach for your household's money. It pulls your bank transactions through the EU's open-banking rules (PSD2, via
Enable Banking), sorts them with rules, your own notes and, only for what is left, a language model, and then
answers questions like "why was September expensive?" and "which subscriptions should we review?" with numbers computed by code, not
guessed by a model. Everything is stored in an encrypted database on your own machine.

It is built for one household in France or Italy, runs on macOS or Linux (or in Docker), and costs nothing beyond the model you choose.

Not financial advice. The coach explains your own spending and saving habits. It does not recommend investments, loans or insurers, and
gives no tax or legal advice. Estimates (a mortgage renegotiation, a cancellation date) are labelled as estimates.

A personal open-source project. It is maintained by one person who is not a financial, tax or legal professional (FR: AMF / CIF; IT: Consob),
it has not been audited by a third party, it is not a regulated service and it comes with no warranty (MIT). You run it on your own
machine, with your own bank data, at your own risk; read docs/security.md before you trust it with a bank.

Why you can trust it with bank data

• No model in the data path. Syncing, deduplication, recurring-payment detection, forecasts and budgets are plain code. A model labels
  only the merchants the rules and your memory leave open, and answers questions on request.
• Numbers come from code, words come from the model. The coach calls read-only tools that return computed, redacted results (account
  and people pseudonyms, hashed transaction references, generalised merchants); it never adds up raw rows, and every claim carries its evidence.
• Your data stays yours. The database is encrypted (SQLCipher); keys live in the macOS Keychain (or a 0600 secrets folder in Docker);
  the web app listens on 127.0.0.1 only behind a one-time login link; there is no telemetry, CDN or analytics.
• You can see and cut every outbound path. coach privacy status lists them (bank API, the model backend, optional alert channels),
  coach privacy report shows a local journal of every call (host, size, purpose: never a payload), and [privacy] local_only = true makes
  the whole thing run on a local model (Ollama) with the bank sync as the only network use.
• The coach cannot change your records by itself. It can only propose changes to the household memory; you accept them yourself in a
  terminal. Destructive commands (wipe, plain export) need a terminal and a typed phrase.

Details: docs/privacy.md (data flows, retention, delete / export) and docs/security.md (threat model, residual risks).

What it does

Screenshots

Made on the synthetic demo household of scripts/demo/ (every name, bank and amount is invented). The full tour, the screencasts and
the user guide are on the documentation site: https://mmornati.github.io/ai-finance-coach/

Dashboard	Ask the coach	Subscriptions
Loans & net worth	Kids' money	Memory and proposals

Try it yourself without a bank or a model: uv run python scripts/demo/seed_demo.py --home /tmp/coach-demo, then
scripts/demo/run_demo.sh /tmp/coach-demo (Try the demo).

Install

Pick one. All three end with coach init and coach doctor.

1. With uv or pipx (macOS, Linux)

uv tool install ai-finance-coach        # or: pipx install ai-finance-coach   (Python 3.11+; uv fetches one for you)
coach init                              # your private home (see below)
coach doctor

Try it without installing: uvx --from ai-finance-coach coach doctor. From a release file: uv tool install ./ai_finance_coach-X.Y.Z-py3-none-any.whl.
The package ships the built web app, the database migrations and the data files. (Installing straight from a git URL does not include the
web app, which is not committed: use a release, or build it from a checkout as in section 3.)

An installed package keeps its files in ~/.ai-finance-coach (set COACH_HOME to change it; a config.toml in the current folder wins).

2. With Docker Compose (Linux, macOS, no Keychain needed)

cp -r <this repository> coach && cd coach           # or download a release
mkdir -p secrets coach-home/data coach-home/memory coach-home/config && chmod 700 secrets
for k in db_key backup_key proposal_key; do (umask 077; head -c 32 /dev/urandom | base64 | tr '+/' '-_' | tr -d '=\n' > secrets/$k); done
export COACH_UID=$(id -u) COACH_GID=$(id -g)
docker compose build
docker compose run --rm coach setup enablebanking   # then: docker compose run --rm coach setup
docker compose up -d                                # the web app on http://127.0.0.1:8765 only

The container runs as a non-root user with a read-only root filesystem, publishes the app on your loopback only, reads secrets from files,
and has no claude command (use the Anthropic API or Ollama). Back up secrets/ in your password manager. Everything about it, including the
daily-job service and connecting a bank from a container: docs/docker.md. (The Docker files are checked statically in the
tests; building the image needs network access and is not part of the automated checks.)

3. From source (to develop or contribute)

git clone https://github.com/mmornati/ai-finance-coach.git && cd ai-finance-coach
uv sync                                  # Python and all wheels; no brew needed
(cd web && pnpm install && pnpm build)   # the web app is built, not committed
uv run coach init
uv run coach doctor

See CONTRIBUTING.md.

Quick start (about 10 minutes)

1. coach init (1 min). Creates config.toml from the commented example, a private data folder, an empty memory skeleton (templates
   only), and the secrets (after you type generate; the values are never shown: back them up). Then an empty encrypted database.
2. coach doctor shows what is ready and what to do next.
3. coach setup enablebanking (5 min). Walks you through creating your own Enable Banking application in restricted mode: account,
   application, redirect URL to whitelist, the downloaded key, linking your accounts. Everyone needs their own application; none is shipped.
4. coach setup (4 min plus bank logins). The first-run wizard, resumable: connect your first bank (your browser opens on your bank's own
   login page), first sync (the longest history the bank allows), normalize and categorize (it first prints exactly what a model would receive,
   explains which backend gets it, and asks you to type send; or go fully local), then the onboarding interview about your household.
   Nothing leaves your machine without a typed confirmation at the step that does it.
5. coach ui opens the web app through a one-time login link. Ask the coach, review categories, set budgets.
6. Optional: coach schedule install (macOS) or coach schedule loop / the Docker scheduler profile for the daily job.

Architecture

 Enable Banking (PSD2) ──┐   CSV / OFX / CAMT imports ──┐
                         ▼                              ▼
              ┌────────── ingest: sync, dedup, pending, balances, consents ──────────┐
              │                                                                      ▼
   memory/ (md + yaml,    ┌─ classify: bank parsers → memory notes → rules → kNN → LLM (long tail only, redacted)
   yours, local) ───────► │                                                          │
              ▲           └──────────────► encrypted SQLite (SQLCipher) ◄────────────┘
              │                                   │
              │            analytics (deterministic): averages, recurring, forecast, budgets, loans, net worth
              │                                   │
              │     finance MCP server: read-only, redacted tools + memory PROPOSALS (never writes)
              │                                   │
              └── you accept ◄── Coach runtime: Claude Code (claude -p) │ Anthropic API │ Ollama (local)
                                                  │
                    Web app (127.0.0.1, one-time login)  ·  CLI  ·  scheduler (launchd / loop)  ·  alerts (local; opt-in channels)

More: docs/architecture.md.

Safety model for AI coding agents

If you run Claude Code (or another agent) in this folder, treat it as untrusted code running as you: it can read files and run commands with
your permissions. The project ships guard rails and a template:

• The agent talks to the data only through the finance MCP tools (redacted, read-only) and can only propose memory changes.
• docs/claude-settings.example.json is a template of Claude Code permission rules built from the
  categories in docs/security.md: memory integrity, the web app's secrets and state, driving the web app, confirmation
  bypass (--yes), decisions and outside contact, destructive and plain-export commands, the Keychain, backups, and the configuration file
  (which holds the privacy switches). Copy it to .claude/settings.json of the project where you run the agent, read every line, and adjust.
  .claude/settings.json is git-ignored because it can hold absolute paths of your machine.
• coach security audit checks permissions, leftovers and exposure; CLAUDE.md gives the agent its working rules.

Permission rules mitigate; they do not prevent. The residual risks are listed honestly in docs/security.md.

Documentation

Honest limits

• One household, France and Italy (rules tables, taxonomy, bank description parsers). Other countries need parsers and rules: see CONTRIBUTING.
• Enable Banking's restricted mode covers your own accounts; each bank consent lasts at most 180 days and is renewed with coach reconnect.
  Who they are, what they see and keep, and exactly which read-only calls this app makes: docs/enable-banking.md.
• The claude-code backend uses your personal Claude subscription through claude -p and is meant for low-frequency personal use; use the API or
  Ollama for automation or sharing.
• LLM labels and answers can be wrong; they carry an "AI-generated" label, and every figure is checked against the tools' results.
• Alpha-quality in places: run coach backup before you trust it with a new bank, and read the residual risks.

License

MIT. Contributions are accepted under the same licence.