Financial Compass

Know where you stand. Know your options. Plan your next move.

Financial Compass is a privacy-first, local-first CLI that answers one question calmly and factually:

If my income stops tomorrow, how long can I survive, what are my options, and what should my plan be?

It never predicts when you'll find a job, never gives personalized investment/tax/legal advice, and never classifies your investments as halal/haram. It just does the arithmetic, clearly, on your own machine.

Why

Most "financial planning" tools are either sales funnels for investment products or vague budgeting apps that don't answer the actual question people have during a layoff or income scare: how long do I have, and what are my real options? Financial Compass is a calculator, not an advisor — it separates facts (your transactions, balances, debts) from assumptions (job search length, spending cuts) and scenarios (what-if projections), so you always know which is which.

Principles

• Local-first. Your financial data never leaves your machine. No bank credentials, ever.
• No mandatory cloud or AI APIs. Everything runs offline.
• Facts vs. assumptions vs. scenarios, always labeled. Nothing is presented as certain that isn't.
• No job-search-duration predictions. You choose the horizon; the tool just does the math.
• No personalized investment, tax, or legal advice. And no automatic halal/haram classification of your holdings.
• Calm, factual, scenario-based — never fear-driven.

Install

pip install financial-compass

Requires Python 3.11+.

Try it in one command

pip install financial-compass
financial-compass demo

This runs the entire workflow against bundled, made-up synthetic data — no setup, no real financial data touched — and opens the generated HTML report.

Quick start (with your own data)

# 1. Create a local workspace and fill in your assets/liabilities/income facts
financial-compass init
$EDITOR .financial-compass/facts.yaml

# 2. Import a bank statement (CSV or XLSX exported from your bank)
financial-compass import statement.csv

# 3. See categorized spending and burn rates
financial-compass analyze

# 4. Simulate income stopping tomorrow
financial-compass simulate --months 12

# 5. See the salary thresholds that matter
financial-compass salary

# 6. Get a calm, month-by-month action plan
financial-compass plan

# 7. Generate a full offline HTML dashboard
financial-compass report --html

Try it immediately with the bundled synthetic example data:

financial-compass init --workspace demo-workspace --force
cp examples/facts.yaml demo-workspace/facts.yaml
financial-compass import examples/sample_statement.csv --workspace demo-workspace
financial-compass report --html --workspace demo-workspace --output demo-report.html

What it does

1. Bank statement analysis — imports CSV/XLSX, categorizes transactions with local keyword rules, detects recurring income/expenses, and calculates actual / essential / reduced / survival monthly burn.
2. Assets — cash, FDs, mutual funds, Indian/US stocks, RSUs (vested/unvested), EPF, PPF, NPS, gold, property — classified as immediate / accessible / long-term liquidity.
3. Liabilities — home/car/personal/education loans, credit cards, and their EMIs.
4. Layoff simulation — assumes income stops tomorrow, includes notice pay, severance, leave encashment, and pending bonus, and projects month-by-month asset drawdown for 3/6/9/12/18/24-month horizons.
5. Job planning — simulates a new job starting after N months at a chosen salary, and computes four thresholds: survival, minimum sustainable, recovery, and target salary.
6. Action plan — a calm, practical month-by-month plan (Month 0, 1-3, 3-6, 6-9, 9-12, 12+) with concrete options to extend runway at each stage.
7. What-if scenarios — lower spending, temporary income, different job-search durations, different new-job salaries, all compared side by side.
8. HTML report — a single self-contained offline dashboard covering net worth, liquid assets, spending, runway, scenarios, salary thresholds, the action plan, and every assumption used to produce them.

Python API

from financial_compass import storage
from financial_compass.core.spending import calculate_burn_rates
from financial_compass.core.simulation import simulate_layoff

profile = storage.load_profile()
transactions = storage.load_transactions()
burn = calculate_burn_rates(transactions)
result = simulate_layoff(profile, burn.survival, months=12)
print(result.runway_months)

Data & privacy

• All data lives in a local workspace directory (.financial-compass/ by default) as plain YAML/JSON files you can read, edit, back up, or delete yourself.
• No bank credentials are ever requested — you export a statement file from your bank and point the tool at it.
• No network calls are made by any core command.

Development

git clone https://github.com/rameezrz25/financial-compass
cd financial-compass
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pre-commit install

ruff check .
mypy .
pytest

See CONTRIBUTING.md for more.

License

MIT — see LICENSE.