expense-tracker

name	expense-tracker
description	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.
version	1.0.2
category	finance
tags	["expenses","budget","finance","spending","personal-finance","tracking","reports","money","frugal","budgeting","natural-language","local"]

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

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:

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

User Says	AI Action
"spent $45 at Costco"	Parse → add expense → confirm → check budget
"how much have I spent this month?"	Run query.sh for current month → format summary
"am I over budget?"	Run budget-check.sh → report status
"weekly report"	Generate weekly report from template
"what did I spend on food?"	Query Groceries + Dining categories
"I got a $20 refund from Amazon"	Log negative amount → confirm
"split a $90 dinner with Jake"	Calculate half → log $45 → confirm
"that last one should be Entertainment, not Shopping"	Update most recent entry's category
"set grocery budget to $700"	Update budgets.json
"how much is left in my dining budget?"	Calculate: limit - spent this month
"show me everything from last week"	Query with date range, detail format
"what's my biggest expense this month?"	Query + sort by amount
"cancel that last expense"	Delete most recent ledger entry
"spent $5.50 at starbucks yesterday"	Parse date as yesterday → add expense
"vet bill was $280"	Log as Pets category
"car insurance came out, $180"	Log as Insurance category
"I spent like 50 bucks at Target"	Log $50, confirm amount approximation
"got reimbursed $45 from work"	Log as negative (reimbursement)
"how much did I spend on food this month?"	Query Groceries + Dining combined
"compare this month to last month"	Generate month-over-month comparison

---

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

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%