ray-finance: a local-first AI financial advisor that runs in your terminal

The gap ray-finance targets: dashboards that show, advisors that tell

Most personal finance tools stop at categorization. You get a pie chart of last month's spending and the implicit instruction to feel something about it. The README makes this the central pitch: "Other finance apps show you what you spent. Ray tells you what to do." The intended user is someone who already knows roughly where the money went and wants a decision instead of another visualization.

The README's own comparison is the clearest statement of scope. Asked how to handle debt, a general chatbot returns percentages and emergency-fund rules of thumb; a budgeting app returns a chart; ray-finance is documented to return a specific instruction that names the balance, the interest rate, the monthly amount to redirect, and the month the debt clears. Whether the model reliably produces that quality of answer is not something the repository demonstrates, and the example is the maintainer's illustration rather than a measured output. But it defines the product's ambition precisely: a recommendation engine over your real numbers, not a reporting layer.

How the profile, the encrypted store and the model fit together

The architecture visible in package.json and the README is a single Node process with three moving parts. Bank data arrives through the plaid SDK (and, per the README, Bridge for European accounts), lands in a local SQLite database accessed through libsql, and is encrypted at rest with AES-256 using DB_ENCRYPTION_KEY. A separate key, PLAID_TOKEN_SECRET, encrypts the stored Plaid access tokens, which is a sensible split: compromising the database passphrase should not automatically expose the credentials that can pull fresh data.

The AI layer is provider-agnostic. Dependencies include both @anthropic-ai/sdk and openai, and setup offers Anthropic, OpenAI, Ollama for local inference, or any OpenAI-compatible endpoint. The mechanism that separates ray-finance from a chat wrapper is the persistent profile. Every conversation is documented to load your financial profile first: family, income, goals, strategy, key decisions, open items. The README also states that the profile updates itself when your situation changes and that facts mentioned in passing are retained across sessions. That is the whole product thesis compressed into a data flow: sync, store, load context, answer with the context attached.

The interface is built with Ink and React, so the terminal UI is component-driven rather than a readline loop. An Express dependency and the Dockerfile's EXPOSE 9876 point at the local HTTP surface used for the Plaid OAuth return redirect.

Installing ray-finance and running your first commands

The package ships on npm and requires Node 18 or later, per the engines field. The README gives one install line:

npm install -g ray-finance

After that, the fastest way to see what the tool does without touching a bank account is the demo mode. It seeds a database of realistic fake data, and every dashboard command can then run against it with the --demo flag.

ray demo
ray --demo status
ray --demo spending
ray --demo budgets
ray --demo score

You should see a financial overview, a spending breakdown by category, budget progress, and the 0-100 behavior score with streaks and achievements. The README notes these dashboard commands work with no setup at all, which makes demo mode a genuine evaluation path rather than a marketing screenshot.

To try the AI chat against the fake portfolio you must configure a provider first. The setup wizard writes configuration and the .env.example file lists the keys the application reads.

ray setup

ANTHROPIC_API_KEY=
PLAID_CLIENT_ID=
PLAID_SECRET=
PLAID_ENV=production
DB_ENCRYPTION_KEY=
PLAID_TOKEN_SECRET=

With an AI key in place, ray --demo starts an interactive session over the seeded data. Connecting real accounts is a separate step, ray link. If you use a Plaid OAuth bank such as Chase or Capital One, the README requires PLAID_REDIRECT_URI=http://localhost:9876/oauth-return and the same URL registered in the Plaid dashboard under Team Settings, API, Allowed redirect URIs. Investments and Liabilities are off by default and must be opted into with PLAID_OPTIONAL_PRODUCTS=investments,liabilities; the README warns that enabling them without approval causes ray link to fail.

Where ray-finance breaks down or is the wrong choice

The most concrete constraint is credential dependency. Bring-your-own-keys mode is free, but it assumes you will register for Plaid or Bridge and manage those credentials yourself. That is a materially higher barrier than downloading a budgeting app, and it pushes token management onto you. The Pro mode at $10/mo removes that step by handling API keys, but it also means your data flows through a hosted intermediary for the AI calls, which sits in tension with the local-first framing even though the README states the database stays local.

The second limitation is recovery. The README documents export and import for backup and restore, but the .env.example presents DB_ENCRYPTION_KEY and PLAID_TOKEN_SECRET as plain passphrases with no described rotation, escrow or recovery path. Lose either and the corresponding data is not readable. For a store holding years of transactions, that is a real operational risk, and the documentation does not address it.

Third, this is a single-user CLI. There is no mention of shared household accounts, role separation, or a mobile client. If two partners need to view the same budget from their phones, ray-finance is the wrong tool. It also is not an accounting system: there is no double-entry ledger, no reconciliation workflow, and no audit trail described. Treating its output as tax-ready records would be a mistake. Finally, the recommendation quality depends entirely on the model you point it at, and the repository offers no evaluation of how well any provider performs on the profile-driven prompts.

How ray-finance differs from Monarch, Copilot and YNAB

The README names Monarch, Copilot, YNAB and Mint as the category it is reacting against, and the difference is structural rather than cosmetic. Those products are hosted services with polished web and mobile clients; their value is aggregation plus presentation, and their business model depends on you staying inside their interface. ray-finance inverts both: it runs locally, it is driven from a terminal, and its output is prose advice rather than views.

The practical trade-off is that you give up the client experience. There is no phone app, no shared household view, no drag-and-drop budget editor. In exchange you get a database you control, a model you choose (including Ollama, which means no external API call at all), and an advisor that carries context between sessions. YNAB in particular encodes a budgeting methodology in its interface; ray-finance has no equivalent enforced method, so the discipline has to come from you or from the model's suggestions.

If your actual problem is that you do not know where your money goes, a hosted dashboard will solve it faster and with less setup. ray-finance assumes you have already cleared that bar.

Maintenance, releases and what the MIT licence means here

The repository is not archived, and the last push was on 2026-08-01. Releases are versioned and frequent enough to suggest ongoing work: v0.4.2 on 2026-04-17, v0.5.0 on 2026-05-05, and v0.5.1 on 2026-05-08, with the package.json version matching 0.5.1. Note the gap between the last release and the last push: code has moved since the published version, so installing from npm gives you 0.5.1 rather than whatever is on main. If you need the newest commits you are building from source, and the Dockerfile expects a prebuilt dist directory plus src/public copied alongside it, so the build step is not optional.

Upgrade cost is low by design. The CLI is distributed as a global npm package, so a version bump is one install command, and the data lives outside the package in a local database. The risk sits in schema migrations, which the README does not describe; the export and import commands are the only documented safety net before upgrading.

The MIT licence permits commercial use, modification and redistribution with the copyright notice preserved. That is permissive enough for most personal and internal use. It does not, however, grant anything regarding the third-party services the tool depends on: Plaid and Bridge have their own terms, and Anthropic, OpenAI or any other provider you configure has its own. The licence also offers no warranty, which matters when the software's output is financial advice. Nothing here is legal advice, and the README does not present ray-finance as a regulated advisor.

Editorial conclusion

Adopt ray-finance if you are comfortable in a terminal, already hold or can obtain Plaid or Bridge credentials, and want an advisor that reasons over a profile you maintain rather than a dashboard you stare at. Skip it if you need a mobile app, multi-user support, or an audited accounting ledger; nothing in the repository suggests any of those. Before committing real accounts, run ray demo to exercise every dashboard command, then verify that DB_ENCRYPTION_KEY and PLAID_TOKEN_SECRET are set to distinct strong passphrases, because the README does not document key rotation or recovery if either is lost.

Frequently asked questions

Official sources

1. cdinnison/ray-finance on GitHub
2. License: MIT
3. Project website
4. README
5. Releases