Initial actual-budget skill for Claude Code

Read-only Actual Budget API integration with shell helpers for
querying accounts, transactions, budgets, categories, and spending.

scripts/actual-helper.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Actual Budget helper functions for Claude Code skill
+# Source this file: source "$(find ~/.claude/skills -name 'actual-helper.sh' 2>/dev/null | head -1)"
+
+# Auto-detect the script directory
+ACTUAL_SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ACTUAL_QUERY="${ACTUAL_SKILL_DIR}/actual-query.mjs"
+ACTUAL_CONFIG_DIR="${HOME}/.config/actual-budget"
+
+# Run the Node.js query script
+_actual_run() {
+  node "${ACTUAL_QUERY}" "$@"
+}
+
+# Show current configuration (without password)
+actual_config() {
+  echo "=== Actual Budget Configuration ==="
+  if [[ -f "${ACTUAL_CONFIG_DIR}/config" ]]; then
+    cat "${ACTUAL_CONFIG_DIR}/config"
+  else
+    echo "No config found. Run setup.sh first."
+  fi
+  echo ""
+  echo "Password file: $([ -f "${ACTUAL_CONFIG_DIR}/password" ] && echo "present" || echo "missing")"
+  echo "Node modules: $([ -d "${ACTUAL_SKILL_DIR}/node_modules/@actual-app/api" ] && echo "installed" || echo "not installed")"
+}
+
+# Verify configuration is complete
+actual_check_config() {
+  local ok=true
+  [[ -f "${ACTUAL_CONFIG_DIR}/config" ]] || { echo "ERROR: Config file missing"; ok=false; }
+  [[ -f "${ACTUAL_CONFIG_DIR}/password" ]] || { echo "ERROR: Password file missing"; ok=false; }
+  [[ -d "${ACTUAL_SKILL_DIR}/node_modules/@actual-app/api" ]] || { echo "ERROR: @actual-app/api not installed"; ok=false; }
+  if $ok; then
+    echo "Configuration OK"
+    return 0
+  else
+    echo "Run setup.sh to fix"
+    return 1
+  fi
+}
+
+# List all accounts with balances
+actual_accounts() {
+  _actual_run accounts
+}
+
+# Get account balance(s), optionally filtered by name
+# Usage: actual_balance [account_name]
+actual_balance() {
+  _actual_run balance "$@"
+}
+
+# List all categories
+actual_categories() {
+  _actual_run categories
+}
+
+# List category groups
+actual_category_groups() {
+  _actual_run category-groups
+}
+
+# List available budget months
+actual_budget_months() {
+  _actual_run budget-months
+}
+
+# Get budget summary for a month
+# Usage: actual_budget_month [YYYY-MM]  (defaults to current month)
+actual_budget_month() {
+  _actual_run budget-month "$@"
+}
+
+# List transactions
+# Usage: actual_transactions [account_name_or_id] [start_date] [end_date]
+actual_transactions() {
+  _actual_run transactions "$@"
+}
+
+# Get spending breakdown by category
+# Usage: actual_spending_by_category [start_date] [end_date]
+actual_spending_by_category() {
+  _actual_run spending-by-category "$@"
+}
+
+# List all payees
+actual_payees() {
+  _actual_run payees
+}
+
+# Run an arbitrary ActualQL query
+# Usage: actual_query '<json_query>'
+actual_query() {
+  _actual_run query "$@"
+}
+
+# List available budgets on the server
+actual_budgets() {
+  _actual_run budgets
+}