Budget Skill

When they provide the token:

• Base64 decode it to get the claim URL
• Make a POST request to the claim URL to get the permanent Access URL
• Save this Access URL for the next step

Step 2: Bank Connection

"Now connect your bank accounts via SimpleFIN's web interface:"

1. "Visit the setup URL from SimpleFIN"
2. "Search for your bank and enter your credentials"
3. "SimpleFIN will securely connect to your accounts"

This happens in their browser — you don't need to do anything.

Step 3: Skill Installation

Run the setup:

budget-skill setup

This creates:

• Data directory: ~/.openclaw/workspace/data/simplefin/
• Config file: config.json
• Budget file: budgets.json

Step 4: Configure Access

Edit the config file with the Access URL from Step 1:

# Write to ~/.openclaw/workspace/data/simplefin/config.json
{
  "access_url": "https://USER:[email protected]/simplefin"
}

Step 5: Test Connection

budget-skill accounts

Should list all connected accounts with balances. If successful, guide them to fetch transactions:

budget-skill fetch --days 30

Personalized Merchant Rules

After initial setup, help users create personalized categorization rules.

Generate Personal Categories

1. Fetch recent transactions: budget-skill fetch --days 30
2. Load transaction data: ~/.openclaw/workspace/data/simplefin/transactions/transactions.json
3. Analyze recurring merchants, identify:
   • Car loans (track balance)
   • Subscriptions (monthly/annual)
   • Personal services (gym, trainer)
   • Payment plans
   • Specific merchant names vs generic transfers
4. Create workspace/skills/budget-skill/personal-categories.json with:
   • Merchant-specific rules
   • Category mappings
   • Balance tracking (for loans)
   • Notes about frequency

Template structure:

{
  "merchant_rules": {
    "MERCHANT NAME": {
      "category": "CATEGORY",
      "notes": "Description",
      "frequency": "monthly",
      "track_balance": true,
      "current_balance": 0.00,
      "last_updated": "YYYY-MM-DD"
    }
  },
  "category_descriptions": { ... }
}

See personal-categories.example.json in the skill directory for full template.

Financial Context File (Optional)

For deeper context (especially for financial accountability), create: workspace/skills/budget-skill/financial-context.md

Include:

• User's financial goals (saving for house, paying off debt, etc.)
• Recurring payment details
• Known merchant mappings
• Budget preferences
• Account balance history

Always read this file before generating reports to provide personalized, contextual advice.

Core Commands

All commands use the global budget-skill binary.

Fetch Accounts

budget-skill accounts

Returns all connected accounts with current balances. Run this before generating reports to get fresh data.

Fetch Transactions

budget-skill fetch --days 30

Pulls transactions from the last N days. SimpleFIN returns transactions nested in account responses, so this extracts and categorizes them.

Note: First-time bank connections may take 24 hours to populate transaction history.

Set Budget

budget-skill budget set --category FOOD_AND_DRINK --limit 500 --period monthly

Creates spending limits. Available periods: monthly, weekly

Check Budget Status

budget-skill budget status --period monthly

Compares actual spending vs budgets for current period. Highlights over-budget categories.

Generate Report

budget-skill report --period weekly

Shows spending breakdown by category, top merchants, and totals. Available periods: weekly, monthly

Providing Financial Insights

When analyzing spending:

1. Read context first: Check financial-context.md if it exists for user goals and preferences
2. Categorize accurately: Use personal rules to identify specific merchants
3. Flag wasteful spending: Highlight food delivery, expensive meals, unused subscriptions
4. Quantify impact: Show how cutting expenses affects savings goals
5. Be specific: "Uber Eats $45 this week" not "delivery expenses increased"

Report Structure

Weekly/Monthly Reports:

• Total spending by category
• Current account balances
• Top merchants
• Flags for wasteful spending
• Actionable recommendations

Daily Reviews:

• List today's transactions
• Updated balances
• Flag suspicious or unusual charges
• Call out impulse purchases

Budget Accountability

If user has set financial goals (in financial-context.md or BUDGET.md):

• Evaluate ALL spending through that lens
• Calculate impact on savings goal (e.g., "$50 delivery = $50 less for down payment")
• Be direct about wasteful spending
• Track progress toward goals

Spending Categories

Personalized Categories (from personal-categories.json):

• AUTO_LOAN - Car loan payments (track balance)
• SUBSCRIPTIONS - Software/services
• CREDIT_CARD_PAYMENT - Credit card autopay
• SAVINGS - Investment contributions
• PERSONAL_SERVICES - Personal trainer, services
• PAYMENT_PLANS - Installment payments

Generic Categories (fallback):

• FOOD_AND_DRINK
• TRANSPORTATION
• GENERAL_MERCHANDISE
• ENTERTAINMENT
• PERSONAL_CARE
• TRAVEL
• UTILITIES
• HOUSING
• TRANSFER
• UNCATEGORIZED

Data Storage

All data lives in: ~/.openclaw/workspace/data/simplefin/

• config.json - SimpleFIN Access URL (contains credentials)
• accounts/accounts.json - Connected accounts
• transactions/transactions.json - Categorized transactions
• budgets.json - Budget limits by category

Security: All data is local. Access URL acts as password — never expose it.

Troubleshooting

"Config not found"
→ Run budget-skill setup first

"No transactions found"
→ Run budget-skill fetch --days 30

Empty transactions for a bank
→ Some banks take 24 hours to sync. Check again tomorrow.

Balance showing as cents instead of dollars
→ SimpleFIN returns balances as dollar strings, not cents. CLI should parse as-is.

"Please add your SimpleFIN Access URL"
→ Config file is missing the Access URL or still has placeholder text

Automated Reports

For recurring budget reviews, set up cron jobs:

Weekly Report (Sunday 7 PM):

{
  "schedule": {"kind": "cron", "expr": "0 19 * * 0", "tz": "America/Chicago"},
  "payload": {
    "kind": "agentTurn",
    "message": "Generate weekly budget report:\n1. Read financial-context.md\n2. Run: budget-skill accounts\n3. Run: budget-skill fetch --days 7\n4. Run: budget-skill report --period weekly\n5. Analyze spending, flag waste, provide recommendations"
  }
}

Daily Review (10 PM):

{
  "schedule": {"kind": "cron", "expr": "0 22 * * *", "tz": "America/Chicago"},
  "payload": {
    "kind": "agentTurn",
    "message": "Daily transaction review:\n1. Read financial-context.md\n2. Run: budget-skill accounts\n3. Review today's transactions\n4. Flag suspicious or wasteful spending"
  }
}

Best Practices

1. Always fetch fresh data before generating reports
2. Read financial-context.md for personalized insights
3. Update personal-categories.json when new recurring merchants appear
4. Track loan balances and report progress when payments appear
5. Be specific in recommendations — "Cut Uber Eats" not "reduce food spending"
6. Respect user goals — if saving for a house, evaluate all spending through that lens

Example Workflow

User asks: "How much did I spend this week?"

1. budget-skill accounts (refresh balances)
2. budget-skill fetch --days 7 (get recent transactions)
3. budget-skill report --period weekly (generate report)
4. Read financial-context.md (if exists)
5. Analyze output:
   • Summarize spending by category
   • Show top merchants
   • Flag wasteful spending (food delivery, impulse buys)
   • Compare to budget (if set)
   • Provide actionable recommendations
6. Present findings in conversational format

References

• SimpleFIN API: https://beta-bridge.simplefin.org/info/api
• Repository: https://github.com/benminer/openclaw-budget-skill
• Setup Guide: See README.md in skill directory