A personal finance tracker for income, spending, savings, and tax estimation. Built as a local-first Next.js app with optional iCloud sync.

• Paystub parsing — Upload paystub PDFs and extract data automatically via Google Gemini AI
• Tax estimation — Federal, NY, and NJ income tax calculations with real-time projections
• Spending tracking — Monthly spending log with categories and year-over-year comparison
• Savings tracking — Track savings and investment accounts over time
• iCloud sync — Store data in iCloud Drive for seamless sync across Macs
• Git backup — Optional automatic git commit/push of your data directory
• Desktop app — Native macOS wrapper via desktop-app/

npm install
npm run dev

Open http://localhost:3000 — the app will redirect you to the setup wizard on first run.

The setup wizard lets you:

1. Choose a data directory (defaults to iCloud Drive)
2. Set your starting year
3. Optionally enter your Gemini API key

Copy .env.example to .env.local and fill in values:

cp .env.example .env.local

Budge stores all financial data as JSON files in your chosen data directory:

budge-data/
  profile.json          # Your tax filing info
  2026/
    income.json         # Paystub and income data
    spending.json       # Monthly spending entries
    savings.json        # Savings account snapshots
    tax-estimates.json  # Tax projection data

The default path (~/Library/Mobile Documents/com~apple~CloudDocs/budge-data) syncs automatically via iCloud Drive.

App configuration is stored in .budge-config.json in the project root (gitignored).

Build a native macOS app wrapper from the desktop-app/ directory:

cd desktop-app
./build.sh

This creates Budge.app which runs the Next.js dev server in a native window.

• Next.js 16 with App Router
• TypeScript
• Tailwind CSS 4
• shadcn/ui components
• Recharts for data visualization
• Google Gemini API for document parsing