ray-finance

You already know where the money went. That's the easy part — every app does it. The part that's missing is what to do about it. Ray is that part.

Tell Ray about your family, goals, and strategy once. From then on, every answer is a real recommendation grounded in your actual numbers — not another chart, not generic advice. Ask "can I afford this?" and Ray gives you a yes, a no, or a "not yet, and here's what would change that." Open source. Local-first. Encrypted.

Why Ray is different

Dashboards show. Ray tells. Monarch, Copilot, YNAB, Mint — they sort your transactions into pie charts and call it insight. You still have to figure out what to do next. Ray closes that loop: it takes your real bank data, factors in your goals and situation, and hands you the decision.

Example — you ask "how should I deal with my debt?"

• ChatGPT: "Aim to save 15–20% of your income. Consider a 3–6 month emergency fund, then focus on high-interest debt."
• Your budgeting app: A pie chart of debt payments by month.
• Ray: "You've got $34,200 across two cards and a car loan. At $95k with a baby coming in March, pause the Japan fund and throw that $440/mo at the Chase card — it's at 24.9%. That clears it by September and frees up $340/mo before the baby arrives."

That's the difference. Ray doesn't describe your situation back to you. It tells you what to do about it.

Features

It gets smarter every conversation

• Your situation, always loaded — Every conversation starts with your financial profile: family, income, goals, strategy, key decisions, and open items. Ray reads it all before you type a word.
• Self-updating context — Got a raise? Had a baby? Decided to pay off debt aggressively? Ray updates your profile automatically when your situation changes.
• Long-term memory — Mention you're saving for a house or that you cancelled a subscription. Ray remembers across every future conversation.

Stay on track without trying

• CFO personality — Ray doesn't list options. It tells you what it would do and why, references your goals, and flags problems you haven't noticed yet.
• Daily scoring — A 0-100 behavior score with streaks and 14 unlockable achievements. No restaurants for a week? That's Kitchen Hero. Five zero-spend days? Monk Mode.
• Budgets and goals — Track spending limits by category and progress toward financial goals.
• Smart alerts — Large transactions, low balances, budget overruns.

Your data never leaves your machine

• Encrypted local database — All data stays on your machine in an AES-256 encrypted SQLite database.
• PII masking — Names, account numbers, and identifying details are scrubbed before anything reaches the AI. Your data is analyzed, not exposed.

Set it and forget it

• Bank sync via Plaid or Bridge — Connect checking, savings, credit cards, investments, and loans. Plaid supports 🇺🇸 United States and 🇨🇦 Canada. Bridge supports 🇪🇺 Europe (France and the broader EU via PSD2).
• Scheduled daily sync — Automatic bank sync via launchd (macOS) or cron (Linux).
• Auto-recategorization — Define rules to automatically re-label transactions.
• Export/import — Back up and restore your financial data.

Install

npm install -g ray-finance

Try It

Explore Ray with realistic fake data — no bank accounts needed.

ray demo                # seed a demo database
ray --demo status       # financial overview
ray --demo accounts     # linked accounts with balances
ray --demo spending     # spending breakdown by category
ray --demo budgets      # budget tracking
ray --demo goals        # financial goal progress
ray --demo score        # daily score, streaks, achievements
ray --demo alerts       # financial alerts
ray --demo transactions # recent transactions

The dashboard commands work with no setup at all. To also try the AI chat with demo data, run ray setup first and add an API key (Anthropic, OpenAI, or any OpenAI-compatible provider) — then ray --demo will start an interactive session where you can ask questions about the fake portfolio.

When you're ready to connect real accounts, run ray link.

Quick Start

ray setup

The setup wizard offers two modes:

Pro (quick setup)

We handle the API keys. Your data stays local. $10/mo.

1. Enter your name
2. Get a Ray API key (opens Stripe checkout)
3. Link your accounts — checking, savings, credit cards, investments, loans, mortgage
4. Done — daily sync auto-scheduled at 6am

Bring your own keys

Bring your own AI and banking credentials. Free forever.

1. Pick your AI provider — Anthropic, OpenAI, Ollama (local), or any OpenAI-compatible endpoint
2. Enter your API key and pick a model
3. Enter your banking credentials — Plaid for 🇺🇸/🇨🇦 (get free keys), Bridge for 🇪🇺 Europe (get free keys), or both
4. Link your accounts — checking, savings, credit cards, investments, loans, mortgage
5. Done

Plaid OAuth banks (Chase, Capital One, etc.) redirect through their bank's site, so you must:

• Set PLAID_REDIRECT_URI=http://localhost:9876/oauth-return (use your RAY_PORT if you changed it).
• In your Plaid dashboard → Team Settings → API → Allowed redirect URIs, register the same URL. http://localhost is allowed by Plaid for local dev.

Plaid optional products — Investments and Liabilities are off by default. If your Plaid account is approved for them, opt in with PLAID_OPTIONAL_PRODUCTS=investments,liabilities. Leaving them on without approval will cause ray link to fail.

Commands

Run ray --help to see all available commands.

How It Works

  Checking · Savings · Credit · Investments · Loans · Mortgage
                            │
                   Plaid API · Bridge API
                            │
                 ┌──────────▼──────────┐
                 │   Local SQLite DB    │
                 │  (AES-256 encrypted) │
                 └──────────┬──────────┘
                            │
                 ┌──────────▼──────────┐
                 │      ray CLI         │
                 │  insights · tools   │
                 │  scoring · alerts   │
                 └──────────┬──────────┘
                            │
                       LLM API
                     (PII-masked)

Two outbound calls: your bank aggregator (Plaid or Bridge) and your AI provider (PII-masked). Supports Anthropic, OpenAI, Ollama, and any OpenAI-compatible endpoint. Your financial data is never stored off your machine. No telemetry. No analytics.

Apple Card

Apple Card isn't supported by Plaid, so Ray provides a CSV importer. Export your transactions from card.apple.com — the web portal lets you pick any date range, unlike the Wallet app which is limited to single statements. Then:

ray import-apple ~/Downloads/apple-card.csv --balance 1847.32

On first run Ray creates an "Apple Card" manual account. On subsequent monthly imports, rows are deduplicated by a stable hash of the full row content, so re-running is safe. If Apple retroactively updates pending charges or merchant names, use --replace-range to overwrite the CSV's date range authoritatively. Apple's categories are mapped to Ray's category taxonomy so transactions participate in spending, scoring, and budgets like any other account. If you've configured auto-recategorization rules (via the AI advisor's add_recat_rule tool), they're applied automatically after each import — no separate ray sync needed.

Security & Privacy

• All financial data stored locally in ~/.ray/data/finance.db
• Database encrypted with AES-256 (SQLCipher)
• Plaid and Bridge access tokens encrypted at rest with AES-256-GCM
• Config file stored with 0600 permissions
• PII redacted before sending to any AI provider
• No data leaves your machine — only API calls to your bank aggregator (Plaid or Bridge) and your AI provider

Configuration

Ray stores everything in ~/.ray/:

~/.ray/
  config.json          # API keys and preferences (0600 permissions)
  context.md           # Persistent financial context for AI
  data/
    finance.db         # Encrypted SQLite database
    demo.db            # Demo database (created by `ray demo`)
  sync.log             # Daily sync output

Environment Variables

You can also configure Ray via environment variables or a .env file:

ANTHROPIC_API_KEY=          # Anthropic API key (if using Anthropic)
OPENAI_COMPATIBLE_KEY=      # API key for OpenAI or compatible provider
OPENAI_COMPATIBLE_BASE_URL= # Base URL (e.g. https://api.openai.com/v1, http://localhost:11434/v1)
RAY_PROVIDER=               # "anthropic" or "openai-compatible"
RAY_MODEL=                  # Model name (e.g. claude-sonnet-4-6, gpt-4o, llama3.1)
PLAID_CLIENT_ID=            # Plaid client ID (US/Canada banks)
PLAID_SECRET=               # Plaid secret key
PLAID_ENV=production        # Plaid environment
PLAID_REDIRECT_URI=         # Required for OAuth banks (Chase, Capital One). e.g. http://localhost:9876/oauth-return — must also be registered in your Plaid dashboard under Team Settings → API → Allowed redirect URIs
PLAID_OPTIONAL_PRODUCTS=    # Comma-separated, e.g. investments,liabilities — only enable if your Plaid account is approved for them
BRIDGE_CLIENT_ID=           # Bridge client ID (European banks)
BRIDGE_CLIENT_SECRET=       # Bridge client secret
BRIDGE_DEFAULT_EXTERNAL_USER_ID= # Optional: reuse an existing Bridge external_user_id
DB_ENCRYPTION_KEY=          # Database encryption key
PLAID_TOKEN_SECRET=         # Key for encrypting stored Plaid/Bridge tokens
RAY_API_KEY=                # Ray API key (managed mode, replaces the above)

Roadmap

• Bring your own model — use any LLM provider (OpenAI, Ollama, open-source models, etc.)
• Daily digest email — morning summary of your finances

Have an idea? Open a PR.

Support

Questions, feedback, or need help getting set up? Email clark@rayfinance.app or open an issue.

Contributing

git clone https://github.com/cdinnison/ray-finance.git
cd ray-finance
npm install
npm run build
npm link   # Makes 'ray' available globally

PRs welcome. Please open an issue first for large changes.

License

MIT