Expense Tracker#

Track, categorize, and analyze personal/business expenses.

Quick Start#

Log a transaction:

bash

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

Scan a receipt image:

bash

python3 scripts/expense.py scan receipt.jpg

View reports:

bash

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#

CommandDescriptionaddAdd a manual transactionscanOCR a receipt image and extract itemsimportImport CSV bank statementreportGenerate spending reportsbudgetSet/view monthly budgets by categorycategoriesList or edit categoriesexportExport 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):

bash

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