spend-pulseProactive spending alerts via Plaid. Track credit card spending against a monthly budget with pace-based alerts.
Install via ClawdBot CLI:
clawdbot install jbornhorst1524/spend-pulseProactive spending alerts via Plaid. Track credit card spending against a monthly budget with pace-based alerts.
# Install globally
npm install -g spend-pulse
# Or from source
git clone https://github.com/jbornhorst1524/spend-pulse.git
cd spend-pulse
npm install && npm run build && npm link
Verify installation:
spend-pulse --version
Run the interactive setup wizard:
spend-pulse setup
This will:
For Sandbox testing, use these Plaid test credentials when the bank login appears:
user_goodpass_goodAfter setup, run initial sync:
spend-pulse sync
spend-pulse check β Primary CommandReturns alert decision with full context. This is the main command to use.
should_alert: true
reasons:
- 3 new transactions
- end of month approaching
month: "2026-01"
budget: 8000
spent: 6801.29
remaining: 1198.71
day_of_month: 30
days_in_month: 31
days_remaining: 1
expected_spend: 7200.00
pace: under
pace_delta: -398.71
pace_percent: -6
pace_source: last_month
oneline: "Jan: $6.8k of $8k (85%) | $1.2k left | 1 days | > On track"
new_transactions: 3
new_items:
- merchant: Whole Foods
amount: 47.50
category: Groceries
- merchant: Amazon
amount: 125.00
category: Shopping
Alert triggers (should_alert: true when any apply):
spend-pulse syncPull latest transactions from Plaid. Run before check for fresh data.
synced: 16
new: 3
account: "Amex Gold (...1234)"
total_this_month: 6801.29
spend-pulse status [--oneline]Full spending summary, or quick one-liner:
spend-pulse status --oneline
# Jan: $6.8k of $8k (85%) | $1.2k left | 1 days | > On track
spend-pulse recent [--days N] [--count N]Recent transactions (default: last 5 days).
spend-pulse config [key] [value]View or modify settings:
spend-pulse config # show all
spend-pulse config target 8000 # set monthly budget
spend-pulse config timezone America/Chicago
spend-pulse link [--status] [--remove ] Manage linked bank accounts:
spend-pulse link --status # show linked accounts
spend-pulse link # add another account
spend-pulse link --remove <item_id>
spend-pulse chart [-o ] Generate a cumulative spending chart as a PNG image showing:
spend-pulse chart # Writes to ~/.spend-pulse/chart.png
spend-pulse chart -o /tmp/chart.png # Custom output path
Outputs the file path to stdout so you can capture it and attach to messages.
spend-pulse check --chartGenerate a chart alongside the alert check. Adds chart_path to the YAML output:
should_alert: true
chart_path: /Users/you/.spend-pulse/chart.png
# ... rest of check output
# 1. Sync latest transactions
spend-pulse sync
# 2. Check if alert needed, generate chart
spend-pulse check --chart
If should_alert: true: Compose a brief, friendly spending update using the data. Attach the chart image from chart_path β it shows current vs. last month spending at a glance.
If should_alert: false: Stay quiet unless the user asks about spending.
Use the oneline field as the core message, then add context. Always attach the chart image when available β it communicates pace visually better than any text can.
Under pace (positive):
"Quick spending pulse: Jan at $6.8k of $8k, $1.2k left with 1 day to go. Under pace by 12% β nice work!"
[attach chart.png]
On track:
"January update: $5.5k of $8k (69%) with 10 days left. Right on pace. Recent: $125 Amazon, $47 Whole Foods."
[attach chart.png]
Over pace (heads up):
"Heads up β January's at $7.2k of $8k with 5 days to go. About 10% over pace. The travel charges added up."
[attach chart.png]
Over budget:
"January budget: $8.5k spent, about $500 over the $8k target. Something to keep in mind for February."
[attach chart.png]
Guidelines:
new_items if interestingreasons array for contextSpend Pulse paces against last month's actual cumulative spend curve when available, falling back to a linear budget ramp when no prior month data exists.
expected_spend: Where you were at this point last month (or linear ramp fallback)spent: Actual spendingpace_delta: Difference (negative = under, positive = over)pace: under | on_track | overpace_source: last_month (curve-based) or linear (ramp fallback)This means early-month bills (rent, subscriptions) won't trigger false "over pace" alerts if you had similar bills last month.
Example: Day 15, last month you'd spent $4.2k by this point β expected ~$4.2k.
After testing with Sandbox, upgrade to Development mode for real transactions:
spend-pulse setup --upgrade
This clears sandbox data and connects your real bank account.
"Plaid credentials not found": Run spend-pulse setup to configure.
"Access token not found": Run spend-pulse setup to re-authenticate.
"No accounts found": Check spend-pulse link --status and add account if needed.
Stale data: Run spend-pulse sync to refresh from Plaid.
AI Usage Analysis
Analysis is being generated⦠refresh in a few seconds.
Query Copilot Money personal finance data (accounts, transactions, net worth, holdings, asset allocation) and refresh bank connections. Use when the user asks about finances, account balances, recent transactions, net worth, investment allocation, or wants to sync/refresh bank data.
Stripe API integration with managed OAuth. Manage customers, subscriptions, invoices, products, prices, and payments. Use this skill when users want to process payments, manage billing, or handle subscriptions with Stripe. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). Requires network access and valid Maton API key.
QuickBooks API integration with managed OAuth. Manage customers, invoices, payments, bills, and run financial reports. Use this skill when users want to interact with QuickBooks accounting data. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
Advanced financial calculator with future value tables, present value, discount calculations, markup pricing, and compound interest. Use when calculating investment growth, pricing strategies, loan values, discounts, or comparing financial scenarios across different rates and time periods. Includes both CLI and interactive web UI.
Track expenses via natural language, get spending summaries, set budgets
Query and manage personal finances via the official Actual Budget Node.js API. Use for budget queries, transaction imports/exports, account management, categorization, rules, schedules, and bank sync with self-hosted Actual Budget instances.