ray-finance 0.2.0

package/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm install:*)",
+      "Bash(gh api:*)",
+      "mcp__paper__create_artboard",
+      "mcp__paper__write_html",
+      "mcp__paper__get_screenshot",
+      "mcp__paper__delete_nodes",
+      "Bash(npx next:*)",
+      "Bash(npx tsc:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,13 @@
+# Anthropic API key for AI chat — https://console.anthropic.com
+ANTHROPIC_API_KEY=
+
+# Plaid credentials for bank sync — https://dashboard.plaid.com
+PLAID_CLIENT_ID=
+PLAID_SECRET=
+PLAID_ENV=production
+
+# Database encryption key (any strong passphrase)
+DB_ENCRYPTION_KEY=
+
+# Separate key for encrypting stored Plaid access tokens (any strong passphrase)
+PLAID_TOKEN_SECRET=

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,19 @@
+---
+name: Bug Report
+about: Report a bug
+labels: bug
+---
+
+**What happened?**
+
+**What did you expect?**
+
+**Steps to reproduce**
+1.
+2.
+3.
+
+**Environment**
+- OS:
+- Node.js version:
+- Ray version (`ray --version`):

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,9 @@
+---
+name: Feature Request
+about: Suggest a feature
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+**Describe the solution you'd like**

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+## What
+
+## Why
+
+## Test plan

package/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm run build

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.2.0
+
+Initial open source release.
+
+- CLI interface with 13 commands (`ray`, `setup`, `sync`, `link`, `status`, `transactions`, `spending`, `budgets`, `goals`, `score`, `alerts`, `export`, `import`)
+- AI financial advisor powered by Claude with 13+ tools
+- Plaid integration for bank sync (checking, savings, credit cards, investments, loans)
+- Encrypted local SQLite database (AES-256)
+- Daily financial scoring (0-100) with streaks and 14 achievements
+- Budget tracking with overage alerts
+- Financial goal tracking
+- Transaction auto-recategorization via user-defined rules
+- Conversation memory and persistent financial context
+- Data export/import for backup and restore

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing viewpoints and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer at clark@rayfinance.app.
+
+All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing
+
+Thanks for your interest in contributing to Ray.
+
+## Development Setup
+
+```bash
+git clone https://github.com/clarkdinnison/ray-finance.git
+cd ray-finance
+npm install
+npm run build
+npm link
+```
+
+You'll need Plaid and Anthropic API keys to test. Copy `.env.example` to `.env` and fill in your credentials.
+
+## Making Changes
+
+1. Fork the repo and create a branch from `main`
+2. Make your changes
+3. Run `npm run build` to verify the project compiles
+4. Open a pull request
+
+## Code Style
+
+- TypeScript with strict mode
+- ES modules (`"type": "module"`)
+- Prefer simple, direct code over abstractions
+- No unnecessary dependencies
+
+## Reporting Bugs
+
+Open a GitHub issue with:
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Your Node.js version and OS
+
+## Security Issues
+
+See [SECURITY.md](SECURITY.md) for reporting security vulnerabilities. Do not open public issues for security bugs.

package/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:20-slim
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --production
+COPY dist/ ./dist/
+COPY src/public/ ./dist/public/
+EXPOSE 3000
+CMD ["node", "dist/index.js"]

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,168 @@
+# Ray
+
+An open-source CLI that connects to your bank and already knows your finances before you ask.
+
+```
+  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
+
+## Quick Start
+
+```bash
+npx ray-finance 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. Connect your bank
+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. Connect your bank
+4. Done
+
+## 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   │
+                 └──────────┬──────────┘
+                            │
+                  ┌─────────┴─────────┐
+                  │                   │
+           You (terminal)    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)
+```
+
+## Development
+
+```bash
+git clone https://github.com/clarkdinnison/ray-finance.git
+cd ray-finance
+npm install
+npm run build
+npm link   # Makes 'ray' available globally
+```
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security
+
+## Architecture
+
+Ray is local-first. All financial data is stored on your machine in an encrypted SQLite database. No data is sent to Ray servers because there are no Ray servers.
+
+### Encryption
+
+- **Database encryption**: The SQLite database is encrypted at rest using AES-256 via [SQLCipher](https://www.zetetic.net/sqlcipher/) (better-sqlite3-multiple-ciphers). The encryption key is provided during setup and stored in your local config.
+- **Plaid token encryption**: Plaid access tokens are encrypted separately using AES-256-GCM with scrypt key derivation before being stored in the database.
+- **File permissions**: Config and database files are created with `0600` permissions (owner read/write only).
+
+### Data Flow
+
+Ray makes outbound API calls to three services:
+
+| Service | Purpose | When |
+|---------|---------|------|
+| Plaid | Sync bank transactions and balances | `ray sync`, `ray link` |
+| Anthropic | AI-powered chat responses | `ray` (interactive chat) |
+
+No telemetry, analytics, or usage data is collected or transmitted.
+
+### PII Handling
+
+When sending data to the Anthropic API for AI chat, Ray redacts personally identifiable information (account numbers, routing numbers) before transmission and restores it in the response for display.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly:
+
+1. **Do not** open a public GitHub issue
+2. Email **clark@rayfinance.app** with details
+3. Include steps to reproduce if possible
+
+I will respond within 48 hours and work with you to address the issue before any public disclosure.