Every dollar has a story. A personal finance tool built to work with AI. Drop your bank CSVs, get a dashboard, then sit down with Claude and actually talk through your spending.
Mint is dead. YNAB costs $100/year. Every finance app wants you to hand over your bank credentials and trust their cloud. And even when they work, they just show you charts and leave you to figure out the rest.
The thing none of them do is talk to you about your money.
spendstory is different. It's a local Python pipeline that processes your bank CSVs and generates an interactive dashboard -- but the real value is what happens next. The pipeline produces structured JSON outputs (anomalies, recurring charges, uncategorized transactions) that are designed to be reviewed conversationally with an AI assistant like Claude.
Instead of staring at a pie chart wondering "why was March so expensive?", you get a conversation:
"You had a $847 spike in Dining Out this month -- that's 3x your average. There are 4 charges at restaurants in Tulum between March 12-16. Was this a trip?"
You answer, the context gets saved, and next month's report is smarter.
It's a conversation, not a dashboard. Finance apps are passive -- they show you data and hope you notice things. spendstory actively flags anomalies, identifies new subscriptions, and walks you through them one at a time. The AI remembers your context month over month.
Your data never leaves your machine. No bank logins, no cloud sync, no telemetry. CSVs stay on disk, the dashboard is a single HTML file, and config is a gitignored TOML file. Python 3.11+ stdlib only -- zero pip dependencies.
It handles real-world messiness. 8 bank parsers that understand each bank's formatting quirks. Overlapping CSV date ranges are auto-deduped. "UBER *EATS" and "UberEats" and "UBER EATS UBER EATS" all normalize to the same merchant. Amazon orders get broken out by item.
It builds knowledge over time. Monthly Obsidian reports accumulate year-to-date data with month-over-month comparisons. Category corrections feed back into future runs. Your financial picture gets clearer every month.
- Python 3.11+ (already on most Macs and Linux machines)
- Bank CSV exports -- download from your bank's website (the script auto-detects the format from headers)
- An AI assistant (optional but recommended) -- Claude Code, Claude Desktop, or any tool that can read JSON files
- ~15 minutes per month to download CSVs, run the pipeline, and review the output
No sign-ups, no API keys, no credit card required. Clone the repo and go.
git clone https://github.com/matthewod11-stack/spendstory.git
cd spendstory
# Optional: personalize your config
cp config.example.toml config.toml
# Drop your bank CSVs into data/raw/
mkdir -p data/raw
# Run the pipeline
python -m spendstory
# Open the dashboard
open data/output/personal_spend_dashboard.htmlAfter your first run, check the terminal output for "Other" transactions. These are spending the system couldn't categorize -- add keyword rules in spendstory/categorize.py to catch them. Each month, there are fewer.
Capital One, Amex (household + personal), Citi (checking + bankcard), Mercury, Apple Card, Venmo -- plus a generic CSV fallback that auto-detects columns for unsupported banks.
- Download fresh CSVs from your bank accounts (2nd of the month works well)
- Drop them into
data/raw/ - Run
python -m spendstory - Open the dashboard or review the terminal summary
- Walk through flagged anomalies with Claude -- save context for next month
- Obsidian reports auto-generate for completed months with YTD rollups
Python 3.11+ stdlib only -- no pip install, no virtual environment needed to run the app. The only dev dependency is pytest.
# Run the 66-test suite
python3 -m venv .venv
.venv/bin/pip install pytest
.venv/bin/python3 -m pytest tests/ -vThe pipeline runs 7 phases: CSV detection, parsing + dedup, categorization, HTML dashboard, Obsidian reports, recurring detection, and anomaly analysis. The dashboard is a self-contained HTML file generated via Python f-string templating -- no bundler, no build step.
See docs/adding-a-parser.md for how to add support for a new bank.
| Technology | Role |
|---|---|
| Python 3.11+ | Core engine (stdlib only, uses tomllib for config) |
| HTML / CSS / JS | Self-contained dashboard via f-string templating |
| pytest | Dev-only test runner |
| Obsidian (optional) | Monthly report consumption via Dataview queries |