BudgetClaw — Personal Finance Tracker

BudgetClaw stores all financial data locally in a SQLite database at ~/.budgetclaw/budget.db. No cloud, no accounts, no syncing required.

When to Use BudgetClaw

Activate BudgetClaw tools whenever the user mentions:

• Spending, purchases, or expenses ("I spent...", "paid for...", "bought...")
• Income or deposits ("got paid", "received", "salary hit")
• Budgets ("how am I doing on budget?", "set a budget for...")
• Investments or portfolio ("I own shares of...", "what's my portfolio worth?")
• Net worth ("what am I worth?", "show my assets and liabilities")
• Bank or financial data ("import my CSV", "export my transactions")

Natural Language Patterns

Recording Transactions

Amount convention: negative = money out (expenses), positive = money in (income/deposits).

Always use today's date (YYYY-MM-DD) unless the user specifies otherwise. If no account is mentioned, call budgetclaw_get_accounts and use the most appropriate one (e.g., default to checking for everyday purchases).

Querying Spending

Budgets

After setting a budget, immediately call budgetclaw_get_budgets and show the user their budget with actuals.

Portfolio

Always refresh prices before showing portfolio value or net worth.

Net Worth

First-Time Setup Workflow

When a user is new to BudgetClaw (no accounts exist), walk them through setup:

1. Create accounts — call budgetclaw_add_account for each:

   • Checking account (type: checking)
   • Savings account (type: savings)
   • Credit cards (type: credit)
   • Investment/brokerage (type: investment)
   • Crypto wallets (type: crypto)

2. Set opening balances — budgetclaw_update_account_balance for each account

3. Import past transactions — budgetclaw_import_csv if the user has a CSV export from their bank, or enter manually

4. Set monthly budgets — budgetclaw_set_budget for the categories they care about

5. First net worth snapshot — budgetclaw_refresh_prices then budgetclaw_snapshot_net_worth

Response Style

• Be concise. After adding a single transaction, confirm with one line: "Added: -$45.00 · Whole Foods · Food & Dining"
• Summarize batches. When adding multiple transactions at once, confirm them in a table.
• Show context. After adding an expense in a budgeted category, show how much of the budget remains.
• Use today's date for all transactions unless the user says otherwise.
• Never ask for an account ID. Call budgetclaw_get_accounts silently and pick the right one.

Disambiguation

"I paid my credit card" — this is a transfer, not spending:

• Debit from checking: amount=-500, category="Transfers"
• Credit to credit card account: amount=500, category="Transfers"

"I deposited a check" — income or transfer depending on context:

• Paycheck → category="Income", subcategory="Salary"
• Selling something → category="Income", subcategory="Freelance"
• Moving from another account → category="Transfers"

"I refunded X" — a positive transaction in the same category as the original purchase.

Categories Reference

Built-in categories (use budgetclaw_get_categories for the full list):

For uncategorized transactions, use "Other". Suggest budgetclaw_add_category if a user repeatedly uses a category that doesn't exist.

CSV Import

{
  "file_path": "/path/to/transactions.csv",
  "account_id": "<account-id>"
}

The importer auto-detects common column names (date, amount, description, merchant, category). For custom columns:

{
  "mapping": {
    "date": "Transaction Date",
    "amount": "Debit Amount",
    "description": "Memo"
  }
}

Re-importing is safe — duplicates are automatically skipped.

Statement Parsing

Activate this workflow when the user says things like:

• "parse my statement", "import from PDF", "read my bank statement"
• "I downloaded my statement", "process my Chase PDF", "import transactions from my statement"

Workflow:

Key notes:

• Always call budgetclaw_read_statement first — PDF channel previews are truncated; this tool extracts all pages.
• When possible, verify that the sum of imported transactions matches the statement's closing balance or total charges.
• Re-importing the same statement is safe — rows with a matching external_id are silently skipped. Supply external_id on each transaction (e.g. "stmt-{date}-{amount}-{description_hash}") to enable reliable deduplication.
• The imported / skipped counts in the result confirm what happened.

Plaid Integration

Connect real bank accounts to automatically sync transactions and balances.

⚠️ Plaid is not free in production. The sandbox environment is free and uses mock data. The old Development environment was decommissioned in June 2024. For live bank connections, a paid Plaid plan is required. The "200 free Limited Production calls" is a one-time trial only.

Setup

1. Create a Plaid account at dashboard.plaid.com
2. Copy your PLAID_CLIENT_ID and PLAID_SECRET from the dashboard
3. Register https://localhost:8181 as an allowed redirect URI (required for OAuth banks like Chase)
4. Set environment variables:
   • PLAID_CLIENT_ID — your client ID
   • PLAID_SECRET — your secret key
   • PLAID_ENV — sandbox (default) or production
   • PLAID_LINK_PORT — local server port (default: 8181)

Connecting a Bank Account

budgetclaw_plaid_link

This opens Plaid Link in your browser. Sign in to your bank, then return to the terminal. The tool returns { connection_id, institution_name, accounts_found }.

For sandbox testing, use credentials: user_good / pass_good, select "First Platypus Bank".

Syncing Transactions

After linking, use budgetclaw_sync_connection to pull transactions:

Subsequent syncs use cursor-based pagination — only new, modified, or removed transactions are fetched. No duplicates.

Viewing Balances

After syncing, budgetclaw_get_accounts shows the latest balances pulled from Plaid.

OAuth Banks (Chase, BofA, Capital One, Wells Fargo, USAA)

These institutions use OAuth redirect flows. Plaid handles this automatically — the only requirement is that https://localhost:8181 is registered in your Plaid dashboard as a redirect URI.

On first use, the plugin automatically generates a self-signed localhost TLS certificate stored at ~/.budgetclaw/tls/. Your browser will show a certificate warning — click Advanced → Proceed to continue. This is a one-time prompt per browser.

Note: Getting Chase approved in Plaid Production can take up to 6 weeks. Sandbox works immediately with test institutions.

Key Rules

• Dates must be YYYY-MM-DD
• Expenses are negative, income is positive
• Run budgetclaw_refresh_prices before any net worth snapshot
• budgetclaw_get_spending_summary only counts negative amounts (expenses), income is excluded
• Accounts must exist before adding transactions — create them first if needed