Expense Tracker

Track, categorize, and analyze personal/business expenses.

Quick Start

Log a transaction:

python3 scripts/expense.py add --amount 45.99 --category food --desc "Grocery run" --date 2026-03-31

Scan a receipt image:

python3 scripts/expense.py scan receipt.jpg

View reports:

python3 scripts/expense.py report --period month    # this month
python3 scripts/expense.py report --period week     # this week
python3 scripts/expense.py report --category food   # food spending
python3 scripts/expense.py report --budget           # budget vs actual

Commands

| Command | Description | |---------|-------------| | add | Add a manual transaction | | scan | OCR a receipt image and extract items | | import | Import CSV bank statement | | report | Generate spending reports | | budget | Set/view monthly budgets by category | | categories | List or edit categories | | export | Export data as CSV |

Receipt Scanning

The scan command uses OCR to extract:

• Merchant name
• Date
• Line items with prices
• Total amount

Extracted items are auto-categorized using keyword matching (see references/categories.md for rules).

Data Storage

All data stored in ~/.expense-tracker/:

• transactions.json — all transactions
• budgets.json — monthly budget limits
• categories.json — custom categories and rules

Report Formats

Reports show:

• Total spent per category (bar chart ASCII)
• Month-over-month comparison
• Budget utilization percentage
• Top merchants by spend
• Daily/weekly spending trend

CSV Import

Import bank statements (auto-detects columns):

python3 scripts/expense.py import bank_export.csv --date-col Date --amount-col Amount --desc-col Description