Expense Tracker

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:

Parsing Examples

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 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 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 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

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:

# 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-09 --format json

# Get budget status
bash skills/expense-tracker/scripts/budget-check.sh

Include: category breakdown, top expenses, budget status, week-over-week trend.

Monthly Report

Use templates/monthly-report.md as a guide. Generate for "monthly report", "how'd February go", end-of-month reviews.

# Current month data
bash skills/expense-tracker/scripts/query.sh --from 2026-02-01 --to 2026-02-28 --format json

# Previous month for comparison
bash skills/expense-tracker/scripts/query.sh --from 2026-01-01 --to 2026-01-31 --format json

# Budget check
bash skills/expense-tracker/scripts/budget-check.sh 2026-02

Include: full category breakdown, top expenses, weekly breakdown, month-over-month comparison, savings rate (if income is set in budgets.json).

6. Edge Cases

Refunds

• Detect words: "refund", "returned", "got back", "credit", "reimbursement"
• Store as negative amount: add-expense.sh -35 "Shopping" "Amazon" "2026-02-15" "refund"
• Refunds reduce the category total in budget calculations

Splitting Expenses

• "Split $80 dinner with Sarah" → log $40 (user's half)
• "Split 3 ways: $120 at the bar" → log $40
• Confirm the split: "Logging your share: $40 at the bar (Dining). That right?"

Recurring Expenses

• This skill doesn't auto-schedule recurring expenses
• When the user says "Netflix again" or "monthly gym payment", treat as a new entry
• The AI can note: "Want me to remind you about this next month?" (but don't auto-create)

Multi-Item Purchases

• "Spent $150 at Target on groceries and clothes" → Ask user whether to log as one entry or split
• If split: create separate entries per category
• If single: pick the dominant category or ask which one
• "Bought lunch and a coffee at Panera, $22" → single Dining entry is fine (same category)

Multi-Currency (Optional)

• If the user mentions foreign currency: "spent €50 in Paris"
• Log the original amount and note the currency: add-expense.sh 55 "Travel" "Paris restaurant" "2026-02-15" "€50 EUR"
• Convert to USD for budget purposes (ask user for rate or use approximate)
• Default behavior: assume USD unless told otherwise

Corrections

• "Actually that Costco trip was $52, not $45" → Find the recent Costco entry, update amount
• "Delete expense #12" → Remove from ledger using jq --argjson id 12 'map(select(.id != $id))' — always use --arg/--argjson, never interpolate IDs into filter strings
• "Move #12 to Dining" → Update category field

Zero-Expense Days

• Don't alert on no-spend days unless asked
• In reports, show $0 days as positive (savings!)

7. Conversational Patterns

The AI should handle these naturally without requiring commands:

8. Example Full Interaction

User: spent $45 at Costco
AI: ✅ Expense #1: $45.00 at Costco (Groceries) on 2026-02-17

User: grabbed lunch at Chipotle for $12.50
AI: ✅ Expense #2: $12.50 at Chipotle (Dining) on 2026-02-17

User: $150 at Target yesterday
AI: I logged $150 at Target as **Shopping** — was this groceries or more of a general shopping trip?
User: shopping
AI: ✅ Expense #3: $150.00 at Target (Shopping) on 2026-02-16

User: how's my budget looking?
AI:
=== Budget Check: 2026-02 ===
  🟢 OK    Groceries        $345     / $600   (58%)
  🟡 WARN  Dining           $248     / $300   (83%)
  🟢 OK    Shopping         $280     / $300   (93%)
  ⚪ LOW   Gas/Transport    $85      / $250   (34%)
  ...
  TOTAL: $1,245.00 / $4,950 (25%)

⚠️ Heads up — Dining is at 83% and Shopping is at 93% of your February budget.

User: I got a refund from Amazon for $35
AI: ✅ Refund #4: $35.00 from Amazon (Shopping) on 2026-02-17
   Shopping is now at $245 / $300 (82%) for February.

User: weekly report
AI: [generates formatted weekly report from template]

User: set my dining budget to $400
AI: Updated Dining budget: $300 → $400 for this month. You're now at $248 / $400 (62%) — much more breathing room! 🟢

9. Data Format Reference

Ledger Entry (expenses/ledger.json)

[
  {
    "id": 1,
    "amount": 45.00,
    "category": "Groceries",
    "vendor": "Costco",
    "date": "2026-02-17",
    "notes": "",
    "created_at": "2026-02-17T23:32:00Z"
  },
  {
    "id": 2,
    "amount": -35.00,
    "category": "Shopping",
    "vendor": "Amazon",
    "date": "2026-02-17",
    "notes": "refund for headphones",
    "created_at": "2026-02-17T23:45:00Z"
  }
]

Key Rules

• IDs: Incrementing integers, never reused
• Amounts: Always numbers. Positive = expense, negative = refund
• Dates: ISO 8601 YYYY-MM-DD
• Categories: Must match a name in references/categories.json
• created_at: UTC timestamp of when the entry was created

10. Script Reference

All scripts are in skills/expense-tracker/scripts/ and must be run with bash:

# Add an expense
bash skills/expense-tracker/scripts/add-expense.sh 45 "Groceries" "Costco" "2026-02-17" "weekly groceries"

# Query expenses
bash skills/expense-tracker/scripts/query.sh --from 2026-02-01 --to 2026-02-28 --category Dining --format summary

# Check budget
bash skills/expense-tracker/scripts/budget-check.sh 2026-02

Script Arguments

add-expense.sh <amount> <category> <vendor> [date] [notes]

• amount — number (negative for refunds)
• category — category name from categories.json
• vendor — merchant name
• date — YYYY-MM-DD (default: today)
• notes — optional description

query.sh [--from DATE] [--to DATE] [--category CAT] [--vendor TEXT] [--format FMT]

• --from — start date (inclusive)
• --to — end date (inclusive)
• --category — filter by category name
• --vendor — filter by vendor (partial match, case-insensitive)
• --format — summary (default), detail, or json

budget-check.sh [YYYY-MM]

• Optional month argument (default: current month)
• Exit code 0 = all OK, exit code 1 = at least one category ≥ 80%