---
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