ray-finance 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clark Dinnison
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+<p align="center">
+  <img src=".github/ray-logo.png" alt="Ray" width="120" />
+</p>
+
+<p align="center">
+  An open-source CLI that connects to your bank and already knows your finances before you ask.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ray-finance"><img src="https://img.shields.io/npm/v/ray-finance.svg" alt="npm version" /></a>
+  <a href="https://github.com/cdinnison/ray-finance/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://github.com/cdinnison/ray-finance/stargazers"><img src="https://img.shields.io/github/stars/cdinnison/ray-finance.svg?style=social" alt="GitHub stars" /></a>
+</p>
+
+<br />
+
+```
+  Friday, Mar 28
+
+  net worth  $45,230 +$120
+
+  spending   $2,340 this month · $340 less vs last month
+             Dining -$114  ·  Shopping -$142  ·  Groceries -$73
+
+  ▓▓▓▓▓▓▓░  Dining 92%
+
+  ▓▓▓▓░░░░  Emergency fund $18,200/$40,000
+
+  upcoming   Netflix $16 in 3d  ·  Comcast $142 in 6d
+
+  score      72/100  ·  5d no dining  ·  3d on pace
+
+  ──────────────────────────────────────────────────
+
+  ❯ if I quit my job to freelance, how long can I survive?
+
+  Based on your last 3 months: you burn $4,820/mo after
+  fixed costs. With $18,200 in savings, that's
+  3.8 months of runway at current spend.
+
+  Cut dining and shopping to last-month levels and
+  you stretch to 5.1 months. Land one $8k contract
+  in that window and you never dip below $10k.
+```
+
+Open Ray and it shows your net worth, spending vs last month, budget pacing, and upcoming bills — before you type a word. Ask a question and it answers from your real data, not guesses. Local-first. Encrypted. Open source.
+
+## Features
+
+- **It already knows** — Every conversation starts with a real-time financial briefing. Net worth, spending velocity, budget alerts, goal pace, upcoming bills, and your daily score. No "let me look that up."
+- **Bank sync via Plaid** — Connect checking, savings, credit cards, investments, and loans
+- **Encrypted local database** — All data stays on your machine in an AES-256 encrypted SQLite database
+- **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.
+- **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.
+- **Budgets and goals** — Track spending limits by category and progress toward financial goals
+- **PII masking** — Names, account numbers, and identifying details are scrubbed before anything reaches the AI. Your data is analyzed, not exposed.
+- **Smart alerts** — Large transactions, low balances, budget overruns
+- **Auto-recategorization** — Define rules to automatically re-label transactions
+- **Scheduled daily sync** — Automatic bank sync via launchd (macOS) or cron (Linux)
+- **Export/import** — Back up and restore your financial data
+
+## Install
+
+```bash
+npm install -g ray-finance
+```
+
+## Quick Start
+
+```bash
+ray setup
+```
+
+The setup wizard offers two modes:
+
+### Quick setup (managed)
+
+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
+
+### Self-hosted
+
+Bring your own Anthropic and Plaid credentials. Free forever.
+
+1. Enter your Anthropic API key ([get one](https://console.anthropic.com))
+2. Enter your Plaid credentials ([get free keys](https://dashboard.plaid.com/signup))
+3. Link your accounts — checking, savings, credit cards, investments, loans, mortgage
+4. Done
+
+## Commands
+
+Run `ray --help` to see all available commands.
+
+| Command | Description |
+|---------|-------------|
+| `ray` | Interactive AI chat with your financial advisor |
+| `ray setup` | Configure API keys and preferences |
+| `ray link` | Connect a new bank account |
+| `ray sync` | Pull latest transactions and balances |
+| `ray status` | Quick financial dashboard |
+| `ray transactions` | Recent transactions (filterable by category, merchant) |
+| `ray spending [period]` | Spending breakdown by category |
+| `ray budgets` | Budget status and overruns |
+| `ray goals` | Financial goal progress |
+| `ray score` | Daily score, streaks, and achievements |
+| `ray alerts` | Active financial alerts |
+| `ray export [path]` | Export data to a backup file |
+| `ray import <path>` | Restore from a backup file |
+| `ray billing` | Manage your Ray subscription (managed mode only) |
+
+## How It Works
+
+```
+  Checking · Savings · Credit · Investments · Loans · Mortgage
+                            │
+                        Plaid API
+                            │
+                 ┌──────────▼──────────┐
+                 │   Local SQLite DB    │
+                 │  (AES-256 encrypted) │
+                 └──────────┬──────────┘
+                            │
+                 ┌──────────▼──────────┐
+                 │      ray CLI         │
+                 │  insights · tools   │
+                 │  scoring · alerts   │
+                 └──────────┬──────────┘
+                            │
+                      Claude API
+                     (PII-masked)
+```
+
+Two outbound calls: Plaid (bank sync) and Anthropic (AI chat, PII-masked). Your financial data is never stored off your machine. No telemetry. No analytics.
+
+## Security & Privacy
+
+- All financial data stored locally in `~/.ray/data/finance.db`
+- Database encrypted with AES-256 (SQLCipher)
+- Plaid access tokens encrypted at rest with AES-256-GCM
+- Config file stored with `0600` permissions
+- PII redacted before sending to Claude API
+- No data leaves your machine — only API calls to Plaid and Anthropic
+
+## 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
+  sync.log             # Daily sync output
+```
+
+### Environment Variables
+
+You can also configure Ray via environment variables or a `.env` file:
+
+```bash
+ANTHROPIC_API_KEY=     # Anthropic API key for AI chat
+PLAID_CLIENT_ID=       # Plaid client ID
+PLAID_SECRET=          # Plaid secret key
+PLAID_ENV=production   # Plaid environment
+DB_ENCRYPTION_KEY=     # Database encryption key
+PLAID_TOKEN_SECRET=    # Key for encrypting stored Plaid tokens
+RAY_API_KEY=           # Ray API key (managed mode, replaces the above)
+```
+
+## Roadmap
+
+- [ ] Daily digest email — morning summary of your finances
+
+Have an idea? [Open a PR](https://github.com/cdinnison/ray-finance/pulls).
+
+## Contributing
+
+```bash
+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](LICENSE)

package/dist/ai/agent.d.ts

@@ -0,0 +1,2 @@
+import type Database from "libsql";
+export declare function handleMessage(db: Database.Database, userMessage: string): Promise<string>;

package/dist/ai/agent.js

@@ -0,0 +1,93 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { config, useManaged, RAY_PROXY_BASE } from "../config.js";
+import { buildSystemPrompt } from "./system-prompt.js";
+import { toolDefinitions, executeTool } from "./tools.js";
+import { getConversationHistory, saveMessage } from "./memory.js";
+import { logToolCall } from "./audit.js";
+import { redact, unredact } from "./redactor.js";
+const anthropic = new Anthropic(useManaged()
+    ? { apiKey: config.rayApiKey, baseURL: `${RAY_PROXY_BASE}/ai` }
+    : { apiKey: config.anthropicKey });
+function supportsThinking(model) {
+    return /sonnet-4|opus-4/i.test(model);
+}
+export async function handleMessage(db, userMessage) {
+    // Save incoming message
+    saveMessage(db, "user", userMessage);
+    // Load conversation context, truncated to fit token budget
+    const rawHistory = getConversationHistory(db, 30);
+    const MAX_HISTORY_CHARS = 24_000; // ~6k tokens, leaves room for system prompt + response
+    let historyChars = 0;
+    const history = [];
+    for (let i = rawHistory.length - 1; i >= 0; i--) {
+        historyChars += rawHistory[i].content.length;
+        if (historyChars > MAX_HISTORY_CHARS)
+            break;
+        history.unshift(rawHistory[i]);
+    }
+    // Build system prompt and redact PII before sending to API
+    const systemPrompt = redact(buildSystemPrompt(db));
+    // Build messages array from history, redacting PII
+    const messages = history.map(h => ({
+        role: h.role,
+        content: redact(h.content),
+    }));
+    // Ensure last message is the current user message
+    if (messages.length === 0 || messages[messages.length - 1].content !== userMessage) {
+        messages.push({ role: "user", content: redact(userMessage) });
+    }
+    // Extended thinking config
+    const useThinking = config.thinkingBudget > 0 && supportsThinking(config.model);
+    try {
+        // Build API params
+        const apiParams = {
+            model: config.model,
+            max_tokens: useThinking ? 16000 : 4096,
+            system: systemPrompt,
+            tools: toolDefinitions,
+            messages,
+        };
+        if (useThinking) {
+            apiParams.thinking = {
+                type: "enabled",
+                budget_tokens: config.thinkingBudget,
+            };
+        }
+        // Initial API call
+        let response = await anthropic.messages.create(apiParams);
+        // Agentic tool loop
+        while (response.stop_reason === "tool_use") {
+            // Filter out thinking blocks before adding to messages
+            const assistantContent = response.content.filter((b) => b.type !== "thinking");
+            messages.push({ role: "assistant", content: assistantContent });
+            const toolResults = [];
+            for (const block of assistantContent) {
+                if (block.type === "tool_use") {
+                    const result = await executeTool(db, block.name, block.input);
+                    logToolCall(db, block.name, block.input, result, response.usage?.output_tokens);
+                    toolResults.push({
+                        type: "tool_result",
+                        tool_use_id: block.id,
+                        content: redact(result),
+                    });
+                }
+            }
+            messages.push({ role: "user", content: toolResults });
+            response = await anthropic.messages.create(apiParams);
+        }
+        // Extract text response (filter out thinking blocks), restore PII for display
+        const textBlocks = response.content.filter((b) => b.type === "text");
+        const responseText = unredact(textBlocks.map((b) => b.text).join("\n"));
+        // Save assistant response
+        saveMessage(db, "assistant", responseText);
+        return responseText || "I looked into that but couldn't formulate a response. Could you try rephrasing?";
+    }
+    catch (error) {
+        // Log full error internally but don't expose details to user
+        const safeMessage = error.status
+            ? `API error (${error.status})`
+            : "internal error";
+        console.error("AI agent error:", safeMessage);
+        return "Sorry, I had trouble processing that. Could you try again?";
+    }
+}

package/dist/ai/audit.d.ts

@@ -0,0 +1,3 @@
+import type Database from "libsql";
+export declare function logToolCall(db: Database.Database, toolName: string, inputParams: any, resultSummary: string, tokensUsed?: number): void;
+export declare function getAuditLog(db: Database.Database, limit?: number): any[];

package/dist/ai/audit.js

@@ -0,0 +1,6 @@
+export function logToolCall(db, toolName, inputParams, resultSummary, tokensUsed) {
+    db.prepare(`INSERT INTO ai_audit_log (tool_name, input_params, result_summary, tokens_used) VALUES (?, ?, ?, ?)`).run(toolName, JSON.stringify(inputParams), resultSummary.slice(0, 500), tokensUsed || null);
+}
+export function getAuditLog(db, limit = 50) {
+    return db.prepare(`SELECT * FROM ai_audit_log ORDER BY id DESC LIMIT ?`).all(limit);
+}

package/dist/ai/context.d.ts

@@ -0,0 +1,6 @@
+export declare function getContextPath(): string;
+export declare function readContext(): string;
+export declare function writeContext(content: string): void;
+export declare function isContextEmpty(): boolean;
+export declare function replaceContextSection(section: string, content: string): void;
+export declare function createContextTemplate(userName: string): void;

package/dist/ai/context.js

@@ -0,0 +1,93 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
+import { resolve } from "path";
+import { homedir } from "os";
+const CONTEXT_PATH = resolve(homedir(), ".ray", "context.md");
+export function getContextPath() {
+    return CONTEXT_PATH;
+}
+export function readContext() {
+    if (!existsSync(CONTEXT_PATH))
+        return "";
+    try {
+        return readFileSync(CONTEXT_PATH, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+export function writeContext(content) {
+    const dir = resolve(homedir(), ".ray");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(CONTEXT_PATH, content, { encoding: "utf-8", mode: 0o600 });
+    try {
+        chmodSync(CONTEXT_PATH, 0o600);
+    }
+    catch { }
+}
+export function isContextEmpty() {
+    const content = readContext();
+    if (!content || content.trim().length === 0)
+        return true;
+    // Check if it still has placeholder text (template hasn't been filled)
+    const placeholders = ["(Add income sources", "(Linked accounts will appear", "(Add financial goals", "(Add current financial strategy", "(Log important financial decisions", "(Track action items"];
+    const filledSections = placeholders.filter(p => !content.includes(p)).length;
+    // Consider empty if most sections still have placeholder text
+    return filledSections < 2;
+}
+export function replaceContextSection(section, content) {
+    let current = readContext();
+    if (!current) {
+        writeContext(`## ${section}\n${content}\n`);
+        return;
+    }
+    const sectionHeader = `## ${section}`;
+    const sectionIdx = current.indexOf(sectionHeader);
+    if (sectionIdx !== -1) {
+        // Find the next ## heading after this section
+        const afterHeader = sectionIdx + sectionHeader.length;
+        const nextSectionIdx = current.indexOf("\n## ", afterHeader);
+        const before = current.slice(0, afterHeader);
+        const after = nextSectionIdx !== -1 ? current.slice(nextSectionIdx) : "";
+        current = `${before}\n${content}\n${after}`;
+    }
+    else {
+        // Insert before ## Open Items if it exists, otherwise append
+        const openItemsIdx = current.indexOf("## Open Items");
+        if (openItemsIdx !== -1) {
+            current = `${current.slice(0, openItemsIdx)}${sectionHeader}\n${content}\n\n${current.slice(openItemsIdx)}`;
+        }
+        else {
+            current = `${current.trimEnd()}\n\n${sectionHeader}\n${content}\n`;
+        }
+    }
+    writeContext(current);
+}
+export function createContextTemplate(userName) {
+    if (existsSync(CONTEXT_PATH))
+        return; // don't overwrite existing
+    const template = `# Financial Context for ${userName}
+
+## Family
+- ${userName}
+
+## Income
+- (Add income sources and amounts)
+
+## Accounts
+- (Linked accounts will appear after syncing)
+
+## Goals
+- (Add financial goals)
+
+## Strategy
+- (Add current financial strategy and priorities)
+
+## Key Decisions
+- (Log important financial decisions here)
+
+## Open Items
+- (Track action items and follow-ups)
+`;
+    writeContext(template);
+}

package/dist/ai/insights.d.ts

@@ -0,0 +1,3 @@
+import type Database from "libsql";
+export declare function computeInsights(db: Database.Database): string;
+export declare function cliBriefing(db: Database.Database): string | null;