Metadata-Version: 2.5
Name: financial-planner
Version: 0.1.0
Summary: A local, private household budget and long-term financial planner driven by CSVs and YAML.
Project-URL: Homepage, https://github.com/brookisme/financial_planner
Project-URL: Documentation, https://github.com/brookisme/financial_planner/wiki
Project-URL: Issues, https://github.com/brookisme/financial_planner/issues
Author: Brookie Guzder-Williams
License: BSD-3-Clause
License-File: LICENSE
Keywords: 529,budget,household,personal finance,planner,retirement
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: pydantic>=2.6
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: uvicorn>=0.29
Provides-Extra: desktop
Requires-Dist: pillow>=10; extra == 'desktop'
Requires-Dist: pystray>=0.19; extra == 'desktop'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

<sub>🤖 <b>Built with Claude.</b> This project was developed heavily with <a href="https://www.anthropic.com/claude">Claude</a> (Anthropic's AI assistant) using Claude Code.</sub>

# 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](https://github.com/brookisme/financial_planner/wiki).**

<p align="center"><img src="https://raw.githubusercontent.com/brookisme/financial_planner/main/assets/app-overview.png" height="350" alt="The Financial Planner app, showing the monthly planner and the retirement section with fictional demo data"></p>

## Contents

- [Features](#features)
- [Privacy first](#privacy-first)
- [Quick start](#quick-start)
- [Your own plan](#your-own-plan)
- [Commands](#commands)
- [Development](#development)
- [License](#license)

## 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](https://github.com/brookisme/financial_planner/wiki/Privacy-and-Safety).

## Quick start

Install [pixi](https://pixi.sh), then:

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

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

## Your own plan

```bash
pixi run financial_plan init ~/MyFinancialPlan    # create a plan folder
pixi run 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](https://github.com/brookisme/financial_planner/wiki/Desktop-App) page.

Step-by-step guide: [Quick Start](https://github.com/brookisme/financial_planner/wiki/Quick-Start).
Want an AI assistant to set it up with you? See [LLM_SETUP.md](https://github.com/brookisme/financial_planner/blob/main/LLM_SETUP.md).

## Commands

| Command | What it does |
|---|---|
| `financial_plan init [dir] [--demo]` | Create a plan folder (blank, or a copy of the demo). |
| `financial_plan start [dir]` | Open the app. |
| `financial_plan validate [dir]` | Check the config and CSVs. |
| `financial_plan inspect-csv FILE` | Show a CSV's columns and a suggested source entry. |
| `financial_plan export [dir]` / `import FILE` | Share a whole plan (config + data) as one .zip. |
| `financial_plan categorize [dir] [--unmatched]` | Category averages; rows no rule caught. |
| `financial_plan launcher` | Mac: add Financial Planner.app to /Applications. Elsewhere: a desktop shortcut. |

Details: [Command Line](https://github.com/brookisme/financial_planner/wiki/Command-Line).

## Development

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

See [Development](https://github.com/brookisme/financial_planner/wiki/Development).

## License

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