finance-tracker

# Finance Tracker v2.0

Complete personal finance management. Track expenses, recurring subscriptions, savings goals, multi-currency support, and smart insights.

## Installation

```bash
clawdhub install finance-tracker
```

Or add to PATH:
```bash
export PATH="$PATH:/path/to/finance-tracker/bin"
```

## Quick Start

```bash
# Log an expense
finance add 50k "lunch at cafe"

# Log with currency conversion
finance add $20 "online purchase"

# See what you spent
finance report week

# Get smart insights
finance insights
```

---

## Core Commands

### Add Expenses

```bash
finance add <amount> "<description>"
```

**Amount formats:**
- `50000` — plain number
- `50k` — with k suffix (= 50,000)
- `$50` — USD, auto-converts to your currency
- `€100` — EUR
- `100 USD` — explicit currency

**Examples:**
```bash
finance add 50000 "lunch"
finance add 50k "groceries"
finance add $25 "Netflix subscription"
```

### Undo & Edit

```bash
# Remove last transaction
finance undo

# Edit a transaction
finance edit <id> --amount=60000
finance edit <id> --desc="dinner with friends"
finance edit <id> --category=food

# Delete specific transaction
finance delete <id>
```

### View & Search

```bash
finance report [period]    # today, week, month, year, all
finance recent [n]         # last n transactions
finance search "food"      # search by keyword
```

---

## 🔄 Recurring Expenses

Track subscriptions and bills that repeat automatically.

### Add Recurring

```bash
finance recurring add <amount> "<description>" <frequency> [--day=N]
```

**Frequencies:** daily, weekly, biweekly, monthly, quarterly, yearly

**Examples:**
```bash
finance recurring add 110k "mobile provider" monthly --day=1
finance recurring add 50k "Netflix" monthly
finance recurring add 200k "gym membership" monthly --day=15
```

### Manage Recurring

```bash
finance recurring              # List all
finance recurring list         # Same as above
finance recurring due          # Show what's due today
finance recurring process      # Auto-log all due expenses
finance recurring remove <id>  # Deactivate
```

### How It Works

- Recurring expenses track their next due date
- Run `finance recurring process` daily (or in heartbeat) to auto-log
- Each logged expense appears in your regular transactions
- Monthly totals shown in the recurring report

---

## 🎯 Savings Goals

Set targets and track progress towards financial goals.

### Add Goals

```bash
finance goal add "<name>" <target> [--by=DATE] [--current=X]
```

**Examples:**
```bash
finance goal add "New Laptop" 5000000 --by=2026-06-01
finance goal add "Emergency Fund" 10000000
finance goal add "Vacation" 3000000 --by=2026-08-01 --current=500000
```

### Track Progress

```bash
# Add to goal (increment)
finance goal update "Laptop" 500k

# Set exact amount
finance goal set "Laptop" 2000000

# View all goals
finance goal
finance goal list
```

### Goal Features

- **Deadline tracking** — shows days remaining
- **Daily/weekly/monthly targets** — how much to save to hit deadline
- **Priority levels** — high, medium, low
- **Completion tracking** — celebrate when you hit targets!

---

## 💱 Multi-Currency

Automatic currency conversion with live exchange rates.

### View Rates

```bash
finance rates              # Show all common rates
finance rates USD          # Specific currency rate
finance rates EUR
```

### Convert

```bash
finance convert 100 USD UZS
finance convert 50 EUR USD
```

### Auto-Conversion in Expenses

```bash
# These auto-convert to your default currency (UZS)
finance add $50 "Amazon purchase"
finance add €30 "App subscription"
finance add 100 USD "Online course"
```

### Set Default Currency

```bash
finance currency         # Show current
finance currency USD     # Change default
```

**Rate caching:** Rates refresh every 6 hours automatically.

---

## 💡 Smart Insights

AI-powered spending analysis and alerts.

```bash
finance insights    # Full insights report
finance summary     # Quick daily summary
finance digest      # Weekly digest
```

### What Insights Shows

- **Spending velocity** — daily/weekly/monthly averages
- **Period comparison** — this week vs last week
- **Category changes** — which categories went up/down
- **Anomaly detection** — unusually large expenses flagged
- **Goal progress** — how much to save daily
- **Recurring due** — subscriptions due today

### Example Output

```
💡 Smart Insights
━━━━━━━━━━━━━━━━━━━━━

📈 Spending Velocity
   Daily avg: 85,000 UZS
   This month so far: 1,200,000 UZS
   Projected month total: 2,550,000 UZS

📊 This Week vs Last Week
   📈 Spending UP 23%
   This week: 595,000 UZS
   Last week: 484,000 UZS

🏷️ Notable Category Changes
   🍔 food: ↑ 45%
   🚗 transport: ↓ 20%

⚠️ Alerts
   • Unusually large expense: 350,000 on electronics

🎯 Savings Goals
   Need to save: 50,000 UZS/day
   Next deadline: Laptop in 45 days
```

---

## Income & Assets

### Log Income

```bash
finance income 5000000 "salary"
finance income 500k "freelance project"
```

Income types auto-detected: salary, freelance, business, investment, gift

### Manage Assets

```bash
finance asset add "Bank Account" 10000000 cash
finance asset add "Stocks" 5000000 stocks
finance asset add "Bitcoin" 2000000 crypto
finance asset remove "Old Account"
finance asset list
finance portfolio          # Net worth summary
```

Asset types: cash, stocks, crypto, realestate, savings, investments

---

## Analysis

```bash
finance trends [days]      # Spending patterns over time
finance compare [days]     # Compare current vs previous period
finance budget <daily>     # Check against daily budget
```

### Budget Check

```bash
finance budget 100k
```

Shows:
- Today's spending vs budget
- Week's spending vs weekly budget (7x daily)
- Remaining amounts
- Over-budget warnings

---

## Categories

Auto-detected from description:

| Category | Keywords |
|----------|----------|
| 🍔 Food | lunch, dinner, cafe, restaurant, grocery |
| 🚗 Transport | taxi, uber, bus, metro, fuel |
| 🛍️ Shopping | clothes, shoes, shopping |
| 📱 Tech | phone, laptop, headphones |
| 🎮 Entertainment | movie, game, netflix, spotify |
| 📚 Education | book, course, school |
| 💊 Health | medicine, pharmacy, doctor, gym |
| 🏠 Home | rent, utility, furniture, internet |
| 💇 Personal | haircut, barber, salon |
| 🎁 Gifts | gift, present |
| ✈️ Travel | travel, flight, hotel |
| 🔄 Subscriptions | subscription, monthly, plan |

---

## Data Storage

All data stored locally in `~/.finance-tracker/`:

```
~/.finance-tracker/
├── transactions.json     # All expenses
├── FINANCE_LOG.md        # Human-readable log
├── portfolio.json        # Assets
├── income.json           # Income records
├── recurring.json        # Recurring expenses
├── goals.json            # Savings goals
└── exchange_rates.json   # Cached rates
```

## Export

```bash
finance export csv
finance export json
```

---

## Telegram Integration

For quick logging in chat, common patterns:

```
"spent 50k lunch" → finance add 50000 "lunch"
"taxi 15k"        → finance add 15000 "taxi"
"coffee 8k"       → finance add 8000 "coffee"
```

### Heartbeat Integration

Add to your HEARTBEAT.md for automated processing:

```markdown
## Finance (daily)
- Run: finance recurring process
- Run: finance summary
```

---

## Complete Command Reference

```
EXPENSES:
  finance add <amt> "<desc>"        Log expense
  finance undo                      Remove last
  finance edit <id> [--amount=X]    Edit transaction
  finance delete <id>               Delete transaction
  finance report [period]           Spending report
  finance recent [n]                Recent transactions
  finance search "<query>"          Search

RECURRING:
  finance recurring                 List all
  finance recurring add ...         Add subscription
  finance recurring remove <id>     Remove
  finance recurring process         Log due items
  finance recurring due             Show due today

GOALS:
  finance goal                      List goals
  finance goal add "<name>" <target> [--by=DATE]
  finance goal update "<name>" <amt>
  finance goal set "<name>" <amt>
  finance goal remove "<name>"

CURRENCY:
  finance rates [currency]          Exchange rates
  finance convert <amt> <from> <to>
  finance currency [code]           Get/set currency

INCOME & ASSETS:
  finance income <amt> "<desc>"
  finance asset add/remove/list
  finance portfolio

ANALYSIS:
  finance insights                  Smart analysis
  finance summary                   Daily summary
  finance digest                    Weekly digest
  finance trends [days]
  finance compare [days]
  finance budget <daily>

OTHER:
  finance categories
  finance export [csv|json]
  finance help
```

---

## Tips

1. **Use 'k' for thousands** — `50k` is faster than `50000`
2. **Currency prefix** — `$50` auto-converts
3. **Daily recurring check** — run `finance recurring process` in heartbeat
4. **Weekly insights** — run `finance digest` for summaries
5. **Goal tracking** — update goals when you save money
6. **Budget alerts** — run `finance budget 100k` to stay on track

---

Made with 🦞 by Salen