Personal Finance
Tracker Agent

Build an AI agent that reads your bank statements, categorizes every transaction, and generates monthly spending reports with ASCII charts. Built with OpenCode in under 25 minutes.

Start Building Setup Guide First
Need to set up OpenCode first?

This guide assumes you have OpenCode and a free model provider configured. If you haven't set that up yet:

  1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
  2. Get a free API key from OpenRouter (no credit card needed)
  3. Or follow the full setup guide for detailed steps

You'll also need: A CSV bank statement (or use the sample data we create below).

What You'll Build

By the end of this guide, you'll have a command-line finance tracker that can:

  • Parse CSV bank statements from most major banks (date, description, amount)
  • Auto-categorize transactions into food, transport, entertainment, housing, utilities, shopping, health, and other
  • Generate monthly summaries with totals per category and percentage breakdowns
  • Display ASCII bar charts showing spending distribution right in your terminal
  • Track trends by comparing month-over-month spending
  • Set budget alerts that warn you when a category exceeds your limit

Everything runs locally. Your financial data never leaves your machine -- no cloud services, no third-party access to your bank info.

Keep your financial data private
Never commit real bank statements to a public GitHub repo. Add *.csv and data/ to your .gitignore file. Only commit the Python code, not your personal data.
1

Create Your Project

Set up the project folder with sample data so you can test immediately.

mkdir -p ~/projects/finance-agent/data
cd ~/projects/finance-agent
mkdir -p ~/projects/finance-agent/data
cd ~/projects/finance-agent

Create a sample CSV bank statement so you have test data:

cat > data/march_2026.csv << 'EOF'
Date,Description,Amount
2026-03-01,RENT PAYMENT,-1200.00
2026-03-02,STARBUCKS COFFEE,-5.75
2026-03-03,UBER RIDE,-12.50
2026-03-04,WHOLE FOODS MARKET,-87.32
2026-03-05,NETFLIX SUBSCRIPTION,-15.99
2026-03-06,SHELL GAS STATION,-45.00
2026-03-07,AMAZON.COM,-29.99
2026-03-08,SALARY DEPOSIT,3500.00
2026-03-10,ELECTRIC COMPANY,-95.00
2026-03-11,TRADER JOES,-62.15
2026-03-12,SPOTIFY PREMIUM,-9.99
2026-03-14,CVS PHARMACY,-18.50
2026-03-15,CHIPOTLE MEXICAN,-11.25
2026-03-17,WATER UTILITY,-35.00
2026-03-18,INTERNET SERVICE,-59.99
2026-03-20,TARGET STORE,-43.77
2026-03-22,LYFT RIDE,-8.75
2026-03-23,PIZZA HUT DELIVERY,-22.50
2026-03-25,GYM MEMBERSHIP,-40.00
2026-03-27,COSTCO WHOLESALE,-156.88
2026-03-28,MOVIE THEATER,-14.00
2026-03-30,DENTAL COPAY,-25.00
EOF

Create the AGENTS.md context file:

# Personal Finance Tracker Agent

## Project Type
Python CLI application

## Description
A command-line finance tracker that reads CSV bank statements, categorizes
transactions, generates monthly spending reports, and displays ASCII charts.

## Tech Stack
- Python 3.8+ (standard library only -- csv, json, collections, datetime)
- CSV for input (bank statement format: Date, Description, Amount)
- JSON for configuration (category rules, budgets)

## Conventions
- Use type hints
- Categories: housing, food, transport, entertainment, utilities, shopping,
  health, income, other
- Negative amounts = expenses, positive = income
- Keyword matching for auto-categorization (e.g., "UBER" -> transport)
- ASCII bar charts using block characters
- Store category rules in categories.json so users can customize

Create a .gitignore to protect your financial data:

echo "data/*.csv" > .gitignore
echo "*.csv" >> .gitignore

Save the AGENTS.md file and start OpenCode:

opencode
2

Build the Finance Tracker

One prompt generates the entire finance tracking tool with categorization, reports, and charts.

Type this into OpenCode:

Create a Python script called finance.py that tracks personal spending.
It should have an interactive menu:

1. Import CSV statement (read a CSV file from data/ directory)
2. View transactions (show all, filter by category or date range)
3. Monthly summary (totals per category with percentage of total spend)
4. Spending chart (ASCII horizontal bar chart showing category breakdown)
5. Set budget (set monthly limits per category)
6. Budget check (compare actual spending vs budget, flag overages)
7. Quit

Auto-categorize transactions using keyword matching:
- housing: rent, mortgage, hoa
- food: grocery, restaurant, cafe, coffee, pizza, chipotle, trader, whole foods, costco
- transport: uber, lyft, gas, fuel, parking, transit
- entertainment: netflix, spotify, movie, theater, gaming
- utilities: electric, water, internet, phone, gas company
- shopping: amazon, target, walmart, store
- health: pharmacy, doctor, dental, gym, medical
- income: salary, deposit, transfer in

Store categorization rules in categories.json so they're customizable.
Display the ASCII chart using block characters with colors.
Show percentages and dollar amounts next to each bar.

OpenCode generates the complete script. You'll typically get:

  • A Transaction dataclass with date, description, amount, and category fields
  • A CSV parser that handles different bank statement formats
  • Keyword-based categorization with a customizable rules file
  • ASCII chart rendering with proportional bar widths
  • Budget tracking with over/under indicators
3

Run and Iterate

Test with your sample data and refine the categorization.

Run the finance tracker:

python3 finance.py

Import your sample CSV and generate a report. You should see output like:

================================
  Personal Finance Tracker
================================

1. Import CSV statement
2. View transactions
3. Monthly summary
4. Spending chart
5. Set budget
6. Budget check
7. Quit

Choice: 1
CSV file path: data/march_2026.csv
Imported 22 transactions (21 expenses, 1 income)

Choice: 3

--- March 2026 Summary ---
Total Income:   $3,500.00
Total Expenses: $1,998.33
Net:            $1,501.67

Category Breakdown:
  Housing:        $1,200.00  (60.1%)
  Food:             $339.22  (17.0%)
  Utilities:        $189.99  ( 9.5%)
  Shopping:          $73.76  ( 3.7%)
  Transport:         $66.25  ( 3.3%)
  Health:            $83.50  ( 4.2%)
  Entertainment:     $39.98  ( 2.0%)

Choice: 4

--- Spending by Category ---
Housing       ████████████████████████████████  $1,200.00
Food          █████████                          $339.22
Utilities     █████                              $189.99
Health        ██                                  $83.50
Shopping      ██                                  $73.76
Transport     ██                                  $66.25
Entertainment █                                   $39.98

Iterate with OpenCode

Refine the tracker with follow-up prompts:

# Better categorization
Some transactions are showing as "other". Add these rules:
- "COSTCO" should be "food" not "shopping"
- Any transaction over $500 in "shopping" should be flagged for review

# Fix CSV format
My bank exports CSVs with columns: "Transaction Date", "Post Date",
"Description", "Category", "Type", "Amount". Update the parser to
handle this format too.

# Add color output
Use ANSI color codes: red for categories over budget, green for
under budget, yellow for within 10% of the limit.
Export your bank statements
Most banks let you download transactions as CSV from their website. Look for "Download" or "Export" in your transaction history. Save the file to your project's data/ directory and import it.

Example Prompts to Try

Once the basic tracker works, extend it:

# Multi-month comparison
Add the ability to import multiple months and show a month-over-month
comparison: "You spent 15% more on food in March vs February."

# Recurring expense detection
Detect recurring transactions (same amount, same vendor, monthly
pattern) and list them separately as "fixed expenses."

# Savings goals
Add a savings goal feature: set a target amount and date, and the
tracker shows how much you need to save per month to hit it.

# Export report
Generate a monthly report as a markdown file with the chart,
summary, and top 5 largest expenses. Save to reports/ directory.

# Split transactions
Add the ability to split a single transaction across multiple
categories (e.g., a Costco trip that's 70% food, 30% household).

What's Next?

You've built a working finance tracker. Here are your options:

  • Build a dashboard: Create a web frontend with HTML/CSS charts and deploy to Cloudflare Pages. Generate the HTML report locally, push to GitHub, auto-deploy.
  • Version your code: Push the Python code (not your CSVs) to GitHub so others can use it.
  • Track your dashboard: Add Umami analytics if you build a web version.
  • Professional email: Set up Zoho Mail on your domain if you want to share reports via professional email.
  • Try another agent: Same setup, different task:

Try Another Agent

The pattern is always the same: create a folder, write AGENTS.md, give OpenCode the task. The only thing that changes is the prompt.

Build Shopping Agent All Guides