Bill Ballou
a6e841b4eb
- SKILL.md: Add Presentation Guidelines and Privacy sections for consistent financial data presentation - actual-query.mjs: Support ACTUAL_BUDGET_CONFIG_DIR env var to override default ~/.config/actual-budget/ path, enabling use in containers where that path isn't persisted
135 lines
4.7 KiB
Markdown
135 lines
4.7 KiB
Markdown
---
|
|
name: actual-budget
|
|
description: Use when the user asks about finances, budget, spending, account balances, transactions, categories, or money. Triggers on questions like "how much did I spend", "what's my balance", "budget status", "spending breakdown", "net worth", or any financial query against the Actual Budget server.
|
|
---
|
|
|
|
# Actual Budget Finance Skill
|
|
|
|
Query your Actual Budget instance for financial data — accounts, transactions, budgets, categories, and spending analysis. Read-only access.
|
|
|
|
## Setup
|
|
|
|
Run the setup wizard (one-time):
|
|
|
|
```bash
|
|
SKILL_DIR=$(dirname "$(find ~/.claude -path '*/actual-budget/scripts/setup.sh' 2>/dev/null | head -1)")
|
|
bash "${SKILL_DIR}/setup.sh"
|
|
```
|
|
|
|
The wizard prompts for:
|
|
- **Server URL** — Your Actual Budget instance (default: `https://budget.prettyhefty.com`)
|
|
- **Password** — Server authentication password
|
|
- **Budget sync ID** — Selected from the list of available budgets
|
|
|
|
Configuration is stored in:
|
|
- `~/.config/actual-budget/config` — Server URL, sync ID
|
|
- `~/.config/actual-budget/password` — Server password (chmod 600)
|
|
|
|
Override the config directory by setting `ACTUAL_BUDGET_CONFIG_DIR` environment variable.
|
|
|
|
## Using the Helper Functions
|
|
|
|
Source the helper script:
|
|
|
|
```bash
|
|
source "$(find ~/.claude -path '*/actual-budget/scripts/actual-helper.sh' 2>/dev/null | head -1)"
|
|
```
|
|
|
|
### Available Functions
|
|
|
|
**Configuration:**
|
|
- `actual_config` — Show current configuration
|
|
- `actual_check_config` — Verify configuration is complete
|
|
|
|
**Accounts:**
|
|
- `actual_accounts` — List all accounts with current balances
|
|
- `actual_balance [name]` — Get balance for specific account (fuzzy match by name)
|
|
|
|
**Budget:**
|
|
- `actual_budget_months` — List all months with budget data
|
|
- `actual_budget_month [YYYY-MM]` — Budget summary for a month (defaults to current)
|
|
|
|
**Transactions:**
|
|
- `actual_transactions [account] [start_date] [end_date]` — List transactions (all accounts if none specified)
|
|
- `actual_spending_by_category [start_date] [end_date]` — Spending breakdown by category
|
|
|
|
**Reference Data:**
|
|
- `actual_categories` — List all categories
|
|
- `actual_category_groups` — List category groups
|
|
- `actual_payees` — List all payees
|
|
- `actual_budgets` — List budgets available on server
|
|
|
|
**Advanced:**
|
|
- `actual_query '<json>'` — Run an arbitrary ActualQL query
|
|
|
|
### Output Format
|
|
|
|
All functions output JSON. Amounts are in decimal format (e.g., `123.45`), not Actual's internal integer format.
|
|
|
|
## Common Query Patterns
|
|
|
|
### "How much did I spend this month?"
|
|
```bash
|
|
actual_spending_by_category "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)"
|
|
```
|
|
|
|
### "What's my balance across all accounts?"
|
|
```bash
|
|
actual_accounts
|
|
```
|
|
|
|
### "Show me transactions for Groceries this month"
|
|
First get categories to find the ID, then query transactions and filter:
|
|
```bash
|
|
actual_categories # find the category ID
|
|
actual_transactions "" "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)" # then filter by category in the JSON output
|
|
```
|
|
|
|
### "Am I over budget this month?"
|
|
```bash
|
|
actual_budget_month "$(date +%Y-%m)"
|
|
```
|
|
The result includes `budgeted`, `spent`, and `balance` per category.
|
|
|
|
### "What did I spend at [payee] recently?"
|
|
```bash
|
|
actual_transactions "" "2026-01-01" "$(date +%Y-%m-%d)"
|
|
```
|
|
Then filter the JSON output by payee name.
|
|
|
|
## ActualQL Quick Reference
|
|
|
|
For complex queries, use `actual_query` with a JSON query object:
|
|
|
|
```bash
|
|
actual_query '{"table":"transactions","filter":{"date":{"$gte":"2026-03-01"}},"select":["date","amount","payee","category"]}'
|
|
```
|
|
|
|
**Operators:** `$eq`, `$lt`, `$lte`, `$gt`, `$gte`, `$ne`, `$regex`, `$like`, `$oneof`, `$and`, `$or`
|
|
|
|
**Tables:** `transactions` (primary), plus accounts, categories, payees accessible via the helper functions.
|
|
|
|
## Troubleshooting
|
|
|
|
- **"Config not found"** — Run `setup.sh`
|
|
- **"@actual-app/api not installed"** — Run `cd <skill-scripts-dir> && npm install @actual-app/api`
|
|
- **Connection errors** — Check server URL and password in `~/.config/actual-budget/config`
|
|
- **Empty results** — Verify the sync ID matches an active budget (`actual_budgets`)
|
|
|
|
## Presentation Guidelines
|
|
|
|
- Format currency with dollar signs and commas ($1,234.56)
|
|
- Amounts are already in dollars — do not divide by 1000
|
|
- Highlight categories over budget
|
|
- Summarize before showing details — lead with the key insight
|
|
- For transaction lists, show date, payee, category, and amount in a clean table
|
|
- When computing frequency ("how often"), count unique dates, not transaction count
|
|
- Verify arithmetic before presenting — sanity-check that "X out of Y" values are logically possible
|
|
- Prefer concrete numbers over vague summaries
|
|
|
|
## Privacy
|
|
|
|
- Financial data is private to the family
|
|
- Present data matter-of-factly without judgment
|
|
- Do not modify transactions unless explicitly requested by Bill
|