watch-my-money

Analyze transactions, categorize spending, track budgets, flag overspending.

Workflow

1. Get Transactions

Ask user for bank/card CSV export OR pasted text.

Common sources:

• - Download CSV from your bank's online portal
• Export from budgeting apps
• Copy/paste transactions from statements

Supported formats:

• - Any CSV with date, description, amount columns
• Pasted text: "2026-01-03 Starbucks -5.40 CHF"

2. Parse & Normalize

Read input, normalize to standard format:

• - Auto-detect delimiter (comma, semicolon, tab)
• Parse dates (YYYY-MM-DD, DD/MM/YYYY, MM/DD/YYYY)
• Normalize amounts (expenses negative, income positive)
• Extract merchant from description
• Detect recurring transactions (subscriptions)

3. Categorize Transactions

For each transaction, assign category:

Categories:

• - rent, utilities, subscriptions, groceries, eating_out
• transport, travel, shopping, health
• income, transfers, other

Categorization order:

1. 1. Check saved merchant overrides
2. Apply deterministic keyword rules (see common-merchants.md)
3. Pattern matching (subscriptions, utilities)
4. Heuristic fallback

For ambiguous merchants (batch of 5-10), ask user to confirm.
Save overrides for future runs.

4. Check Budgets

Compare spending against user-defined budgets.

Alert thresholds:

• - 80% - approaching limit (yellow)
• 100% - at limit (red)
• 120% - over budget (red, urgent)

See budget-templates.md for suggested budgets.

5. Detect Anomalies

Flag unusual spending:

• - Category spike: spend > 1.5x baseline AND delta > 50
• Subscription growth: subscriptions up > 20%
• New expensive merchant: first appearance AND spend > 30
• Potential subscriptions: recurring same-amount charges

Baseline = previous 3 months average (or current month if no history).

6. Generate HTML Report

Create local HTML file with:

• - Month summary (income, expenses, net)
• Category breakdown with budget status
• Top merchants
• Alerts section
• Recurring transactions detected
• Privacy toggle (blur amounts/merchants)

Copy template.html and inject data.

7. Save State

Persist to ~/.watch_my_money/:

• - state.json - budgets, merchant overrides, history
• INLINECODE2 - machine-readable monthly data
• INLINECODE3 - interactive report

CLI Commands

CODEBLOCK0

Output Structure

Console shows:

• - Month summary with income/expenses/net
• Category table with spend vs budget
• Recurring transactions detected
• Top 5 merchants
• Alerts as bullet points

Files written:

• - INLINECODE4
• INLINECODE5
• INLINECODE6

HTML Report Features

• - Collapsible category sections
• Budget progress bars
• Recurring transaction list
• Month-over-month comparison
• Privacy toggle (blur sensitive data)
• Dark mode (respects system preference)
• Floating action button
• Screenshot-friendly layout
• Auto-hide empty sections

Privacy

All data stays local. No network calls. No external APIs.
Transaction data is analyzed locally and stored only in ~/.watch_my_money/.