Eternal Expense Tracker

Track, categorize, and analyze personal expenses via receipt scans, manual input, CSV imports, budget tracking, and detailed spending reports.

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