_{🤖 Built with Claude. This project was developed heavily with Claude (Anthropic's AI assistant) using Claude Code.}

Financial Planner

A private, local household budget and long-term planner. Point it at the CSV exports from your bank and credit cards, describe your household (in the app or in YAML), and explore your monthly budget, college savings, retirement and how spending changes over time.

Full documentation: the wiki.

Contents

• Install the Mac app (no code)
• Features
• Privacy first
• Quick start (terminal)
• Your own plan
• Commands
• Development
• License

Install the Mac app (no code)

1. Download the app from the Releases page: FinancialPlanner-macos-arm64.zip for Apple Silicon (M1 and later) or -x86_64.zip for Intel.
2. Unzip it and drag Financial Planner into Applications.
3. The first time, right-click the app › Open › Open (it isn't signed by Apple yet).
4. The first launch sets itself up (a few minutes, needs the internet), then asks how to start: a new plan, a plan someone shared with you, a folder you already have, or the demo.

The planner opens in your browser.

The menu-bar icon appears at the top right of your screen while the app runs. Click it for:

Closing the browser tab leaves it running in the menu bar; opening the app again reuses it. Quit stops it.

Sharing your plan (e.g. with your partner): menu-bar icon › Save Plan as File… (or Settings › Share plan) makes one .zip with your settings, CSV data and scenarios. They open it with menu-bar icon › Open Plan File…, or choose "Open a plan someone shared with me" on their first launch. The file holds your real transactions, so share it privately (AirDrop, Messages). To send just a what-if, use Share in the Scenarios bar instead.

More: Desktop App on the wiki.

Features

• Monthly planner: every category at its average; change any number and see what's left over.
• Explore spending: monthly charts, top merchants and every transaction.
• College 529s: a projection for each child against the cost of college.
• Retirement: income at each retirement age from pensions, accounts, investments and Social Security.
• Spending over time: how costs change as children leave home and after retiring.
• Scenarios: save, compare and share what-ifs, or share the whole plan as one file.
• Settings and categorizing in the app: no YAML editing required (but it's there if you want it).

Privacy first

Everything runs on your computer and nothing is uploaded. Your plan folder holds real financial data: keep it out of public repositories and off the internet, and use generic names (Partner A, Child 1). See Privacy and Safety.

Quick start (terminal)

For people comfortable with a terminal (any OS). With Python 3.11+, install from PyPI and open the demo:

pip install financial-planner                      # add [desktop] for the Mac menu-bar app
financial_plan init ~/FinancialPlan-Demo --demo
financial_plan start ~/FinancialPlan-Demo

Your browser opens at http://127.0.0.1:8765 with a fictional demo household.

Or from source with pixi (for development):

git clone https://github.com/brookisme/financial_planner.git
cd financial_planner
pixi run demo

Your own plan

financial_plan init ~/MyFinancialPlan    # create a plan folder (prefix with `pixi run` from source)
financial_plan start ~/MyFinancialPlan   # open it

Put your bank and card CSV exports in ~/MyFinancialPlan/data/, then click the gear (Settings) at the top right to add your household, connect the CSVs and categorize. On a Mac, pixi run financial_plan launcher adds a Financial Planner app to Applications (menu-bar icon, opens in the browser). A no-code download is described in the Desktop App page.

Step-by-step guide: Quick Start. Want an AI assistant to set it up with you? See LLM_SETUP.md.

Commands

Details: Command Line.

Development

pixi run -e dev test-all     # Python + forecast-math tests
pixi run -e dev web-build    # rebuild the web app

See Development.

License

BSD 3-Clause. Not financial advice: projections are rough and depend on the assumptions you enter.