Payday 💸

A local-first cashflow planning app. Model your household income, bills, and transfers as recurring events, then project balances and guilt-free spending buffers weeks into the future.

Runs in your browser via a local server — launch it with payday, close the tab when you're done. Your data stays on your machine.

Install

pip install payday-planner

Or with uv:

uv tool install payday-planner

Then run it from anywhere:

payday

The app opens at http://localhost:8501. On first launch it loads a demo setup — your data auto-saves between sessions once you configure your own blueprint.

Features

• Dashboard — Net worth snapshot, per-person guilt-free spending buffers, account balances, 90-day cashflow projection chart, and a 14-day upcoming events checklist
• Accounts — Track chequing, savings, debt, investment, and liability accounts with balances and ownership
• Events — Define recurring or one-time money movements (inflows, outflows, transfers) with flexible frequencies and optional end dates
• Timeline — Browse all upcoming events in a calendar view, filterable by owner
• Flow Diagram — Auto-generated Mermaid diagram showing how money moves between accounts
• Oracle — AI assistant (Gemini or Ollama) with full context of your setup; can answer questions and propose blueprint updates
• Export / Import — JSON blueprint for full backup/restore, plus CSV export and Mermaid diagram download

Your Data

Your financial blueprint is stored locally at:

• macOS: ~/Library/Application Support/payday/blueprint.json
• Linux: ~/.local/share/payday/blueprint.json
• Windows: %APPDATA%\payday\blueprint.json

It auto-saves on every page render and auto-loads on startup. To point at a different file:

PAYDAY_BLUEPRINT=~/Documents/finances.json payday

Concepts

Accounts

Each account has a type and an owner:

Events

Events are the engine of the app. Each event is a recurring or one-time money movement:

Guilt-Free Buffer

The guilt-free buffer is the monthly amount left in each person's chequing account after all committed recurring spending — bills, transfers to the hub, and debt payments. It represents discretionary money that can be spent freely or added to savings without guilt.

Calculated as:

buffer = (recurring inflows into your chequing) − (recurring outflows + transfers out of your chequing)

One-time events are excluded — only true recurring commitments count.

Cashflow Projection

The Dashboard projects all account balances day-by-day for up to 365 days. The Net Worth tab shows total assets minus liabilities over time. The By Account tab lets you compare individual account trajectories.

Transfers to debt or liability accounts correctly reduce what is owed (e.g. a LOC payment lowers the LOC balance, keeping net worth flat).

Oracle (AI Assistant)

The Oracle has full context of your blueprint and can:

• Answer questions about your cash flow ("When does the LOC get paid off?")
• Generate payday checklists ("What do I do on Jan 10th?")
• Propose blueprint updates ("Add a $200/month car fund transfer from Hub to Savings")

When the Oracle suggests a blueprint change, a preview banner appears at the top of the page. Review the JSON diff and click Apply Update to accept it.

Backends

Development

git clone https://github.com/your-username/payday
cd payday
uv sync
uv tool install .

Run tests:

uv run pytest tests/ -v

Project Structure

src/payday/
  app.py       # Streamlit UI
  engine.py    # Calendar, projection, serialization, guilt-free buffer logic
  models.py    # Data models (Member, Account, Event, AllocationRule, Goal)
  cli.py       # Entry point
tests/
  test_payday.py
pyproject.toml