| name | finance-tracker |
| description | Track personal expenses with natural language. Log spending, view reports, search transactions. Works with any AI model. |
Finance Tracker
Track personal expenses with natural language. Simple, accurate, works with any model.
Installation
clawdhub install finance-tracker
Or manually add to your system PATH:
export PATH="$PATH:/path/to/finance-tracker/bin"
Quick Start
Add an expense:
finance add 50000 "lunch at cafe"
View this month's spending:
finance report month
Commands
| Command | Description | Example |
|---|
finance add <amount> "<desc>" | Log an expense | finance add 50000 "lunch" |
finance report [period] | View spending report | finance report week |
finance recent [n] | List recent transactions | finance recent 10 |
finance search "<query>" | Search transactions | finance search "food" |
finance categories | List all categories | finance categories |
finance export [format] | Export data (csv/json) | finance export csv |
finance currency [code] | Get/set currency | finance currency USD |
Periods
For reports, use these period options:
today — Today onlyweek — Last 7 daysmonth — Last 30 days (default)year — Last 365 daysall — All time
Amount Formats
These all work:
50000 — Plain number50k or 50K — With k suffix (= 50,000)"50 000" — With spaces (will be parsed)
Auto-Categorization
Categories are detected automatically from your description:
| Category | Detected Keywords |
|---|
| 🍔 Food | lunch, dinner, breakfast, cafe, restaurant, grocery |
| 🚗 Transport | taxi, uber, bus, metro, fuel, gas |
| 🛍️ Shopping | clothes, shoes, shirt, shopping |
| 📱 Tech | phone, laptop, headphones, charger |
| 🎮 Entertainment | movie, game, netflix, spotify |
| 📚 Education | book, course, school, university |
| 💊 Health | medicine, pharmacy, doctor, gym |
| 🏠 Home | rent, utility, furniture, internet |
| 💇 Personal | haircut, barber, salon |
| 🎁 Gifts | gift, present, birthday |
| ✈️ Travel | travel, flight, hotel |
No keyword match? Defaults to ❓ Other.
Output Format
All commands return consistent, parseable output:
Success:
✅ Logged: 🍔 50,000 UZS — lunch at cafe (food)
Report:
📊 This Month's Spending
━━━━━━━━━━━━━━━━━━━━━
💵 Total: 250,000 UZS
🍔 Food: 120,000 UZS (48.0%)
🚗 Transport: 80,000 UZS (32.0%)
📱 Tech: 50,000 UZS (20.0%)
📝 15 transactions
📈 Average: 16,666 UZS
Error:
❌ Invalid amount. Use a positive number.
💡 Usage: finance add 50000 "lunch"
Data Storage
All data is stored locally in ~/.finance-tracker/:
transactions.json — Machine-readable dataFINANCE_LOG.md — Human-readable log
Data is automatically synced to both files.
Examples for Agents
When your human says "I spent 50k on lunch", run:
finance add 50000 "lunch"
When they ask "how much did I spend this week?", run:
finance report week
When they ask "what did I spend on food?", run:
finance search "food"
Tips
- Always quote descriptions with spaces:
"lunch at cafe"
- Use
k for thousands to save typing: 50k instead of 50000
- Check
finance recent to verify transactions were logged
- Categories are case-insensitive
- Data persists across sessions in
~/.finance-tracker/
Made with 🦞 by Salen
