A self-hosted personal finance tool that connects to your bank accounts via Plaid, tracks your recurring expenses, and runs a daily check at 3am to tell you what to pay, when to pay it, and whether you're at risk of overdraft.

Designed to be used alongside Claude AI — ask questions like:

• "Can I afford this $500 expense?"
• "How long to save $5,000 for a trip without cutting anything?"
• "What should I pay today?"

• 🏦 Multi-account support — connect up to 6+ bank accounts, checking, savings, and credit cards across any US institution
• 🔒 Secure local storage — Plaid access tokens are encrypted with AES-256 on your machine; your credentials never leave your computer
• 📋 Expense tracker — manage all recurring bills, loans, subscriptions, and savings goals in a simple JSON file (or by chatting with Claude)
• ⚠️ Overdraft protection — daily check calculates your projected balance after upcoming bills and flags risk before it happens
• 📊 Interactive dashboard — open dashboard.html in your browser for a live financial overview and Q&A chat
• ⏰ Automated daily reports — runs at 3am, saves a markdown report, and delivers a briefing when you open Claude

• Python 3.9+
• A free Plaid developer account (takes ~5 minutes)
• Claude desktop app (for the interactive Q&A features)
• Git

git clone https://github.com/jlqoc/Budgeting.git
cd Budgeting

pip install -r requirements.txt

1. Go to dashboard.plaid.com and create a free account
2. Navigate to Team Settings → Keys
3. Copy your Client ID and Sandbox secret
4. When you're ready for real bank connections, request Development access (free, approved within a day or two)

cp .env.example .env

Open .env and fill in your Plaid credentials:

PLAID_CLIENT_ID=your_client_id_here
PLAID_SANDBOX_SECRET=your_sandbox_secret_here
PLAID_ENV=sandbox

⚠️ .env is gitignored — it will never be committed. Never share this file.

Run the bank linker once per institution:

python connect_banks.py

You'll be prompted to:

1. Create a vault password (used to encrypt your access tokens locally)
2. Choose a bank to link

In sandbox mode, you can use test institutions to try everything out before connecting real accounts. In production mode, you'll go through Plaid's secure OAuth flow for each real bank.

Repeat for each bank account (up to as many as you have).

Open expenses.json and fill in your recurring bills, income, credit cards, loans, and subscriptions. Each item has:

• name — friendly label
• amount — monthly amount in USD
• due_day — day of month it's due (1–28)
• autopay — true if autopay is set up (won't flag as urgent)
• account — which bank account it pulls from (optional label)

Or just tell Claude: "Add my $1,200 rent due on the 1st" and it'll update the file for you.

python daily_check.py

You'll be prompted for your vault password. The script will:

• Fetch live balances from all linked accounts
• Identify bills due in the next 14 days
• Calculate overdraft risk
• Save a report to reports/report_YYYY-MM-DD.md
• Print the advisory to the terminal

Open dashboard.html in your browser. On first load it shows placeholder data. To populate it with live data:

python export_for_dashboard.py

This writes reports/latest.json, which the dashboard reads. Refresh the page to see your live financial snapshot.

crontab -e

Add:

0 3 * * * VAULT_PASSWORD=yourpassword /usr/bin/python3 /path/to/Budgeting/daily_check.py >> /path/to/Budgeting/reports/cron.log 2>&1

1. Open Task Scheduler → Create Basic Task
2. Trigger: Daily at 3:00 AM
3. Action: Start a program
   • Program: python
   • Arguments: "C:\path\to\Budgeting\daily_check.py" --vault-password yourpassword
   • Start in: C:\path\to\Budgeting

If you're using Claude's Cowork mode, the scheduled task is set up automatically via the built-in scheduler.

Budgeting/
├── connect_banks.py        # One-time bank account linker (run once per bank)
├── daily_check.py          # Daily advisory script (runs at 3am)
├── export_for_dashboard.py # Exports live data to dashboard
├── expenses.py             # Expense utilities (imported by other scripts)
├── expenses.json           # Your recurring expenses, bills, goals (edit this)
├── dashboard.html          # Interactive browser dashboard + Claude Q&A
├── requirements.txt
├── .env.example            # Copy to .env and fill in your keys
├── .gitignore              # Keeps .env and tokens/ out of git
├── LICENSE
│
├── tokens/                 # Created automatically — gitignored
│   ├── tokens.enc          # AES-256 encrypted Plaid access tokens
│   └── salt.bin            # Encryption salt
│
└── reports/                # Created automatically — gitignored
    ├── report_YYYY-MM-DD.md
    └── latest.json

• Your bank credentials are never stored. Plaid uses OAuth — you log in directly on your bank's website, and Plaid gives back a token.
• Access tokens are encrypted with AES-256 (Fernet) using a password you choose. They live in tokens/tokens.enc on your machine only.
• tokens/ and .env are gitignored — they cannot be accidentally committed to a public repo.
• Reports are gitignored — your actual financial data never leaves your machine.

Once set up, open Claude and ask things like:

"I want to plan a $5,000 trip. How long will it take to save without changing my budget?"

"I have an emergency expense of $300 — can I pull from my Chase checking without overdrafting?"

"What subscriptions am I paying for that I could cut?"

"Show me a paycheck-by-paycheck plan to pay off my credit card by December."

Claude reads your expenses.json and the latest balance report to give you specific, accurate answers based on your real numbers.

PRs welcome. Some ideas for improvements:

• Web UI for editing expenses (instead of JSON)
• Email/SMS delivery of daily report
• Credit card payoff optimizer
• Multi-currency support
• Transaction categorization and trend analysis

MIT — see LICENSE