Personal budget forecasting CLI application. Import bank statements, categorize transactions, and generate balance forecasts through a terminal UI.
I used to track my budget in a spreadsheet. The recurring question was always: "Can I afford this expense, and when?"
The spreadsheet worked, but it was painful to maintain and nearly impossible to adjust mid-month. I looked at existing tools — they had nice dashboards and direct bank connections, but none could forecast my balance the way I needed, and their budget management was too limited.
So I built my own. Read the full story on my blog.
- Bank import — Load statements from BNP Paribas (Excel) and Swile (JSON)
- Categorization — Automatic and manual categorization of transactions
- Planned operations & budgets — Define recurring expenses, one-time payments, and monthly budgets by category
- Forecasting — Project future balances based on planned operations, budgets, and history
- Operation linking — Match actual transactions to their planned counterparts for accurate forecast updates
- Monthly review — Per-category planned vs actual with consumption bars
- Available margin — Track remaining disposable income with alert threshold
- Category drill-down — Inspect planned sources and matched operations per category
- Terminal UI — Interactive interface built with Textual
- Internationalization — Available in English and French
Monthly Review — Per-category budget tracking with consumption bars and available margin:
Balance — Balance projection chart with past actuals and future forecast:
Operations — Imported transactions with categories and links to planned operations:
Demo data is included so you can try the application without your own bank statements.
# Clone and install
git clone https://github.com/corentin-core/budget-forecaster.git
cd budget-forecaster
python3.12 -m venv venv && source venv/bin/activate
pip install -e .
# Optionally regenerate demo data with fresh dates
python examples/generate_demo.py
# Launch with the demo data
cd examples/
python -m budget_forecaster.main -c config.yamlThe demo database contains categorized operations with planned counterparts and budgets. See examples/README.md for details.
The application follows a layered architecture with clear separation of concerns:
graph TD
Presentation["Presentation — CLI, Terminal UI (Textual)"]
Services["Services — Use cases, forecasting, categorization, import"]
Domain["Domain — Account, Operation, PlannedOperation, Budget, Forecast"]
Core["Core — Amount, DateRange, Category"]
Infrastructure["Infrastructure — SQLite persistence, bank adapters, config"]
Presentation --> Services
Services --> Domain
Domain --> Core
Services --> Infrastructure
See docs/dev/architecture.md for the full layer diagram.
| Area | Tools |
|---|---|
| Language | Python 3.12 |
| UI | Textual |
| Persistence | SQLite |
| Testing | pytest |
| Type checking | mypy (strict mode) |
| Linting | pylint, ruff, autoflake, pyupgrade |
| Formatting | black, prettier |
| CI | GitHub Actions (pre-commit, mypy, pylint, tests+cov) |
| Pre-commit | All of the above, run locally before each commit |
Browse the full documentation at corentin-core.github.io/budget-forecaster:
- User guides — Configuration, forecast, operations, TUI usage
- Developer docs — Architecture, data models, persistence, contributing
- Quality scenarios — Given-When-Then specifications for core features
# Install with dev dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pip install pre-commit && pre-commit install
# Run tests
pytest tests/
# Run tests with coverage
pytest tests/ --cov=budget_forecaster --cov-report=htmlSee docs/dev/contributing.md for the full setup guide.