expense-tracker

Just say what you spent — your AI logs it, categorizes it, and tracks it against your budget. No apps, no forms, no friction. Supports natural language like 'spent $45 at Costco' or 'split a $90 dinner with Jake'. 16 auto-categories, monthly budget alerts, weekly and monthly reports. Runs entirely local — your spending data stays on your machine.

# Expense Tracker Skill

Track, categorize, and budget personal expenses through natural conversation. Users text expenses in plain language and the AI logs them, tracks budgets, and generates reports.

## Skill Directory

```
skills/expense-tracker/
├── SKILL.md                    # This file — AI instructions
├── references/
│   ├── categories.json         # Category definitions + keyword matching
│   └── budgets.json            # Monthly budget limits (user-editable)
├── scripts/
│   ├── add-expense.sh          # Add expense to ledger
│   ├── query.sh                # Query/filter expenses
│   └── budget-check.sh         # Check spending vs budget
├── templates/
│   ├── weekly-report.md        # Weekly report template
│   └── monthly-report.md       # Monthly report template
└── expenses/
    └── ledger.json             # Transaction data (auto-created)
```

---

## 1. Parsing Natural Language Expenses

When a user mentions spending money, extract these fields:

| Field | Required | How to Extract |
|-------|----------|----------------|
| **amount** | Yes | Dollar amounts: "$45", "45 dollars", "forty-five bucks", "45.99" |
| **vendor** | Yes | Named entity after "at", "from", "to", or contextual merchant name |
| **category** | Auto | Match vendor/context against `references/categories.json` keywords |
| **date** | Default today | "today", "yesterday", "last Tuesday", "on 2/14", explicit dates |
| **notes** | Optional | Anything extra the user adds — "for the party", "work expense" |

### Parsing Examples

| User Says | amount | vendor | category | date | notes |
|-----------|--------|--------|----------|------|-------|
| "spent $45 at Costco" | 45 | Costco | Groceries | today | |
| "grabbed lunch for $18 at Chipotle yesterday" | 18 | Chipotle | Dining | yesterday | |
| "$120 electric bill" | 120 | Electric company | Utilities | today | |
| "filled up the tank, 55 bucks at Shell" | 55 | Shell | Gas/Transport | today | |
| "Netflix $15.99" | 15.99 | Netflix | Subscriptions | today | |
| "dropped $200 at Target for birthday stuff" | 200 | Target | Shopping | today | birthday stuff |
| "refund from Amazon $35" | -35 | Amazon | Shopping | today | refund |
| "paid rent $2000" | 2000 | Rent/Landlord | Housing | today | |
| "spent $5.50 at starbucks yesterday" | 5.50 | Starbucks | Dining | yesterday | |
| "vet visit for the dog, $280" | 280 | Vet | Pets | today | |
| "car insurance $180" | 180 | Car insurance | Insurance | today | |
| "groceries and some clothes at Target $150" | 150 | Target | Shopping | today | groceries and clothes (ask user to split or pick) |
| "got reimbursed $45 for work lunch" | -45 | Work | Dining | today | reimbursement |

### Ambiguous Categories

When a vendor could match multiple categories (e.g., "Walmart" could be Groceries or Shopping):

1. **Best-guess first**: Pick the most likely category based on context
2. **Confirm with user**: "I logged $85 at Walmart as **Groceries** — is that right, or was this more of a Shopping trip?"
3. **Remember preferences**: If the user corrects, note the preference for future entries

When no category matches at all, use **Miscellaneous** and tell the user: "Logged under Miscellaneous — want me to put this in a specific category?"

---

## 2. Commands

### `/add` — Log an Expense

Log an expense explicitly.

**Usage:** `/add <amount> <vendor> [category] [date] [notes]`

**Implementation:** Run the add-expense script:
```bash
bash skills/expense-tracker/scripts/add-expense.sh <amount> "<category>" "<vendor>" "<date>" "<notes>"
```

**Examples:**
- `/add 45 Costco` → logs $45 at Costco, auto-categorized, today's date
- `/add 18.50 Chipotle Dining yesterday` → $18.50 dining, yesterday
- `/add -35 Amazon Shopping 2026-02-10 "refund for headphones"` → refund

Most of the time, users won't use `/add` — they'll just say "spent $45 at Costco" and you parse it.

### `/spending` — View Spending

Query expenses with optional filters.

**Usage:** `/spending [period] [category]`

**Implementation:** Run the query script:
```bash
bash skills/expense-tracker/scripts/query.sh [--from DATE] [--to DATE] [--category CAT] [--format summary|detail|json]
```

**Examples:**
- `/spending` → current month summary
- `/spending this week` → this week's expenses
- `/spending Dining` → all dining expenses this month
- `/spending February detail` → detailed February breakdown
- "how much have I spent on groceries?" → query with `--category Groceries`
- "what did I spend last week?" → query with appropriate date range

**Format options:**
- `summary` (default) — totals by category
- `detail` — itemized list with all fields
- `json` — raw JSON output

### `/budget` — Budget Status

Check spending against budget limits.

**Usage:** `/budget [month]`

**Implementation:** Run the budget check script:
```bash
bash skills/expense-tracker/scripts/budget-check.sh [YYYY-MM]
```

**Examples:**
- `/budget` → current month budget status
- `/budget 2026-01` → January budget review
- "how's my budget looking?" → run budget check

**Also supports adjusting budgets:**
- "set my dining budget to $400" → update `references/budgets.json` using `jq --arg` (never interpolate user values into jq code directly)
- "what's my grocery budget?" → read from budgets.json

### `/categories` — View/Manage Categories

Show available categories or recategorize expenses.

**Examples:**
- `/categories` → list all categories
- `/categories Dining` → show Dining keywords and recent expenses
- "move expense #12 to Entertainment" → update ledger entry's category

---

## 3. Category Auto-Matching

Use `references/categories.json` to match vendors to categories. The matching algorithm:

1. **Exact keyword match**: Check if vendor name (lowercased) contains any keyword
2. **Partial match**: Check if any keyword is a substring of the vendor name
3. **Context clues**: Use surrounding words — "lunch at" → Dining, "filled up at" → Gas/Transport
4. **Fallback**: Miscellaneous

### Available Categories
Groceries, Dining, Gas/Transport, Subscriptions, Health/Fitness, Entertainment, Shopping, Utilities, Housing, Personal Care, Education, Gifts, Travel, Insurance, Pets, Miscellaneous.

### Priority Order (when multiple match)
1. Most specific keyword wins ("Costco gas" → Gas/Transport over Groceries)
2. Context from user's message
3. User's historical pattern for that vendor
4. Ask the user

---

## 4. Budget Tracking

Budget configuration lives in `references/budgets.json`. The user edits this to set their limits.

### Alert Thresholds

| Threshold | Emoji | Action |
|-----------|-------|--------|
| < 50% | ⚪ | No alert |
| 50–79% | 🟢 | Informational only |
| 80–99% | 🟡 | Proactive warning: "Heads up — Dining is at 85% of your $300 budget" |
| ≥ 100% | 🔴 | Alert: "You've exceeded your Dining budget ($312 / $300)" |

### When to Alert

- **On every expense**: After logging, silently check the category budget. Only speak up at 80%+ threshold.
- **On `/budget` command**: Show full breakdown with all categories.
- **Weekly**: If generating a weekly report, include budget status section.

### Proactive Budget Warnings

After logging an expense that pushes a category past 80%, add a note:

> ✅ Expense #24: $45.00 at Olive Garden (Dining) on 2026-02-17
> ⚠️ Heads up — Dining is now at $275 / $300 (92%) for February.

After exceeding 100%:

> ✅ Expense #25: $38.00 at Thai Palace (Dining) on 2026-02-19
> 🔴 Dining has exceeded your February budget: $313 / $300 (104%)

---

## 5. Report Generation

### Weekly Report

Use `templates/weekly-report.md` as a guide. Generate when the user asks "weekly report", "how'd I do this week", etc.

**To generate**, run query.sh for the week's date range, then format the results using the template structure:

```bash
# Get this week's data
bash skills/expense-tracker/scripts/query.sh --from 2026-02-10 --to 2026-02-16 --format json

# Get last week for comparison
bash skills/expense-tracker/scripts/query.sh --from 2026-02-03 --to 2026-02