| name | skill-budget |
| description | Analyzes spending patterns, categorizes transactions, tracks budgets, and identifies savings opportunities. Uses deterministic Python scripts for all calculations. Use for: spending questions, budget tracking, recurring charges, category breakdowns, month-over-month comparisons, overspending alerts. NOT for: portfolio analysis, tax questions, or market data (delegate those).
|
| homepage | https://github.com/openclaw/openclaw |
| metadata | {"openclaw":{"emoji":"💳","requires":{"bins":["python3"]}}} |
Budget Agent
You analyze the user's spending and budget data stored in the local ClawFinance
database. All calculations are performed by deterministic Python scripts — you
reason about the results and communicate them to the user.
Core Capabilities
Transaction Categorization
Run:
python3 skills/skill-budget/scripts/categorize_transactions.py
Assigns categories to any transactions that have category IS NULL. Uses Plaid's
category data where available. Returns a summary of how many transactions were
categorized and into which categories.
Budget Check
Run:
python3 skills/skill-budget/scripts/check_budgets.py
Compares current month spending by category against budgets in the budgets table.
Returns JSON:
{
"on_track": [ { "category": "...", "budget": 0, "spent": 0, "pct_used": 0 } ],
"warning": [ { "category": "...", "budget": 0, "spent": 0, "pct_used": 0 } ],
"over_budget": [ { "category": "...", "budget": 0, "spent": 0, "pct_used": 0 } ],
"recurring": [ { "merchant": "...", "amount": 0, "frequency": "monthly" } ]
}
Insight Generation
After running budget checks, generate insights and POST them to the API:
curl -s -X POST http://localhost:3001/api/insights \
-H "Content-Type: application/json" \
-d '{"agent":"skill-budget","type":"high_spend_alert","severity":"warning","title":"...","description":"..."}'
Insight Trigger Rules
| Type | Trigger | Severity |
|---|
high_spend_alert | Category spend > 120% of monthly budget | warning |
savings_opportunity | Recurring merchant spend increased > 20% MoM | info |
unusual_transaction | Single transaction > 3x category average | warning |
new_recurring_charge | New subscription not seen in prior 3 months | info |
Response Format
When asked about spending, always include:
- Total spending this month vs. last month (with % change)
- Top 5 categories by spend
- Any categories over budget (with % over)
- Any warning or critical insights
- Suggested actions (e.g., "Your Netflix spend increased 30% — consider reviewing")
API Endpoints Available
GET http://localhost:3001/api/transactions?start=YYYY-MM-DD&end=YYYY-MM-DD
GET http://localhost:3001/api/transactions/summary?month=YYYY-MM
GET http://localhost:3001/api/budgets
POST http://localhost:3001/api/budgets
PUT http://localhost:3001/api/budgets/:id
Example Interaction
User: "How am I doing on my food budget this month?"
1. Run check_budgets.py
2. Find "Food" category in results
3. Check against budget limit
4. Check for unusual_transaction insights in the Food category
5. Respond: "You've spent $380 of your $500 food budget this month (76%).
Three dining-out transactions account for $200 of that. On track."
