Afrexai Budget Tracker

# Budget & Expense Tracker — AI Agent Financial Command Center

Track every dollar, enforce budgets, spot spending patterns, and build wealth — all through natural conversation with your AI agent.

## How It Works

You talk to your agent naturally: "I spent $45 on groceries" or "How much did I spend on food this month?" The agent maintains a local JSON ledger, enforces your budgets, and gives you weekly/monthly financial intelligence.

---

## 1. Setup — Your Financial Profile

On first use, create `budget-profile.json` in your workspace:

```json
{
  "currency": "USD",
  "monthlyIncome": 5000,
  "payDays": [1, 15],
  "fiscalMonthStart": 1,
  "categories": {
    "housing": { "budget": 1500, "essential": true },
    "food": { "budget": 600, "essential": true, "subcategories": ["groceries", "dining", "delivery", "coffee"] },
    "transport": { "budget": 300, "essential": true, "subcategories": ["fuel", "public", "rideshare", "parking"] },
    "utilities": { "budget": 200, "essential": true, "subcategories": ["electric", "water", "internet", "phone"] },
    "health": { "budget": 200, "essential": true, "subcategories": ["gym", "medical", "supplements"] },
    "entertainment": { "budget": 200, "essential": false, "subcategories": ["streaming", "games", "events", "hobbies"] },
    "shopping": { "budget": 300, "essential": false, "subcategories": ["clothes", "electronics", "home", "gifts"] },
    "education": { "budget": 100, "essential": false, "subcategories": ["books", "courses", "subscriptions"] },
    "savings": { "budget": 500, "essential": true, "target": "emergency-fund" },
    "misc": { "budget": 100, "essential": false }
  },
  "alerts": {
    "budgetWarning": 0.75,
    "budgetCritical": 0.90,
    "unusualSpend": 2.0,
    "dailyMax": 200
  },
  "goals": []
}
```

Customize categories, budgets, and subcategories to your life. The agent adapts to whatever structure you define.

---

## 2. The Ledger — Transaction Format

All transactions live in `budget-ledger.jso...

# 💰 Budget & Expense Tracker — by AfrexAI

Turn your AI agent into a personal finance command center. Track expenses through natural conversation, enforce budgets automatically, get spending insights, and build toward savings goals — all locally, no external APIs.

## Install

```bash
clawhub install afrexai-budget-tracker
```

## What You Get

- **Natural language expense logging** — "spent $45 on groceries" just works
- **Real-time budget enforcement** — alerts at 75%, 90%, and 100% thresholds
- **Spending pace tracking** — predicts if you'll exceed budget before month-end
- **Savings goals** with auto-contribution and progress tracking
- **Weekly & monthly reports** with category trends and merchant analysis
- **Financial health score** (0-100) across 5 dimensions
- **Smart insights** — day-of-week patterns, subscription audits, optimization suggestions
- **Recurring transaction management** — subscriptions tracked automatically
- **100% local** — your financial data never leaves your machine

## Quick Start

Tell your agent: "I spent $45 on groceries at Aldi"

It logs the transaction, checks your food budget, and alerts you if you're spending too fast.

Ask anytime: "Budget check" → see all categories with pace tracking and projections.

## Why This Over Others?

Most budget skills just log numbers. This one thinks:

- **Pace tracking** tells you you're spending 37% faster than sustainable — not just "you spent $380 of $600"
- **Pattern detection** notices your weekend spending is 40% higher
- **Actionable suggestions** like "move $100 from unused transport budget to savings"
- **Financial health scoring** gives you one number to track over time

## ⚡ Level Up Your Financial Operations

This skill handles personal budgeting. For **business financial automation** — invoicing, cash flow forecasting, revenue tracking, P&L analysis — check out our professional context packs:

- 💼 [SaaS Operations Pack](https://afrexai-cto.github.io/context-packs/) — MRR tracking,...