firma

<p align="center"> <img src="https://raw.githubusercontent.com/evan-moon/firma/main/assets/og-image.png" alt="firma" width="560" /> </p> <h1 align="center">firma</h1> <p align="center"> <strong>You earned well this year.<br/>Do you know where it went?</strong> </p> <p align="center"> Drop your trade history into Claude. Get back the full picture —<br/> portfolio, net worth, cash flow — stored in one local SQLite file. No account. No cloud. No catch. </p> <p align="center"> <a href="https://www.npmjs.com/package/@evan-moon/firma"><img src="https://img.shields.io/npm/v/@evan-moon/firma.svg?style=flat&color=cb3837&logo=npm" alt="npm version"></a> <a href="https://github.com/evan-moon/firma/stargazers"><img src="https://img.shields.io/github/stars/evan-moon/firma?style=flat&logo=github&color=ffd700" alt="GitHub stars"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat" alt="License: MIT"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D22-339933?style=flat&logo=node.js&logoColor=white" alt="Node >= 22"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-ready-7c3aed?style=flat" alt="MCP-ready"></a> </p> <p align="center"> <video src="https://github.com/user-attachments/assets/dbdaf14c-fc95-4c66-9d8e-8f674fb8aa7b" controls width="700"></video> </p> --- ``` You: Here's my IBKR trade history [trades.csv]. Set up firma. Claude: I see 47 transactions. Logging in chronological order... done. Syncing prices and FX history... your portfolio: $179K, +61% all-time. TSLA is 78%. You: My portfolio feels really volatile lately. Should I be worried? Claude: TSLA is 74% of your equity — a 10% TSLA move is a 7% net worth move. Cash flow is solid at $6.4k/month saved. The volatility is market, not lifestyle. You: That July expense spike looks alarming. Claude: That was $57k in TSLL — a leveraged bet, not spending. Strip it out: expenses flat at ~$7k/month, savings rate 47.8%. You: Give me a full overview with charts. Claude: Net worth: $294k → $490k in 8 months, pulled back to $427k with TSLA's Q1 dip. [builds net worth trend, income vs expenses, portfolio allocation, unrealized P&L] ``` --- ## Your brokerage app shows you a number. firma shows you the truth. - **It talks to Claude. Natively.** Every command lives behind MCP — log trades, sync prices, render charts, reason about your money. You type plain English; Claude does the rest. - **Local-first, no exceptions.** Everything sits in `~/.firma/firma.db`. No server, no sync, no account. Your financial data never leaves your machine. Ever. - **Nine markets, one source of truth.** US, KRX, KOSDAQ, JP, HK, LSE, XETRA, NSE, TW — plus crypto, commodities, and real estate. Stored in USD, shown in any currency, with *historical* FX from FRED: a 2018 balance gets the 2018 rate, not today's. - **No holdings table to lie to you.** Portfolio, cost basis, P&L — all derived live from your trade log. Nothing drifts out of sync, because there's nothing to drift. - **A brief that actually has an opinion.** `get_market_brief` doesn't dump data — it takes a stance. A weekly lean (aggressive or defensive), a ranked call per holding (BUY / ADD / HOLD / TRIM / SELL / AVOID with conviction and an English thesis), and a watchlist of what to look at next. Every holding is classified, run through a category playbook, and checked by a correlation guard that catches "more of what you already own" before it lands. - **A simulator nobody else ships.** `project_net_worth` runs multi-scenario Monte Carlo over *your* portfolio at *any* horizon — next month or 30 years, one tool. `simulate_scenario` does the deterministic day-to-week version ("PCE comes in hot Thursday — how much does that cost me?"). You supply the assumptions, Claude discloses them verbatim, firma does the math. No hidden "advisor view." - **Time-series features from day one.** The first `firma sync` backfills 90 days of daily history. Correlation, Sharpe, max drawdown, volatility, CAGR — populated immediately, not 30 days from now. - **It tracks your decisions, not just your positions.** `show_thesis_track` reads your own trade reasons back to you against the outcome. `show_anti_portfolio` follows what you sold — the data brokerages hide because it exposes bad exits. --- ## Get started ```bash # 1. Install npm install -g @evan-moon/firma # 2. Set API keys (both free) firma config set finnhub-key YOUR_KEY # finnhub.io — prices, news, earnings firma config set fred-key YOUR_KEY # fred.stlouisfed.org — macro & FX history # 3. Connect Claude Desktop, then restart it firma mcp install ``` **Rather not touch a terminal?** Grab the [macOS](https://github.com/evan-moon/firma/releases/latest/download/firma-mac-arm64.pkg) or [Windows](https://github.com/evan-moon/firma/releases/latest/download/firma-win-x64.exe) installer — Node.js is bundled, Claude is wired up for you. Then **drop your data into Claude** — a CSV, a brokerage export, plain text. It logs everything and syncs prices automatically. > If firma helps you see where your money went, [⭐ star the repo](https://github.com/evan-moon/firma/stargazers) — it's the cheapest way to help others find it. --- ## How it's split: MCP thinks, the CLI keeps you safe firma is **MCP-first**. Analysis, briefs, recommendations, news, valuation, projections — all of it happens in conversation with Claude. The CLI exists for the three things a chat can't safely own: **setup, manual data entry, and repair.** ```bash # Setup firma config set <key> # finnhub-key / fred-key / currency firma mcp install # register with Claude Desktop firma doctor # check keys, data state, FX cache, coverage # Manual entry firma add txn # buy / sell / deposit / dividend / tax — any of 9 markets firma add monthly # month-end balance + cash flow in one flow firma add snapshot # sync prices, snapshot today's portfolio # Repair (when Claude or you got it wrong) firma edit txn / balance / flow / snapshot firma delete txn / ... # alias: firma rm # Verify (read-only — just confirm what landed in the DB) firma show portfolio / txns / balance / flow / snapshot / profile / fx # Sync firma sync # prices (Finnhub) + FX history (FRED) + correlation cache firma sync fx # FX history only ``` Everything analytical — `get_market_brief`, every `show_*`, `report`, `project_net_worth`, `simulate_scenario` — lives in Claude. Two tool families that never mix: **diagnostic** (what's true right now, no fortune-telling) and **thought experiment** (what-ifs, assumptions always disclosed). --- ## Architecture A Yarn Berry monorepo with a strict port-and-adapter layout. The application layer never imports an external API directly — it talks to domain interfaces, and adapters implement them. ``` packages/ domain/ ports + types, zero external-API knowledge external-api/ raw clients (finnhub, fred, worldbank, gdacs, yahoo, …), zero domain knowledge adapter/ the only layer that imports both sides use-case/ business logic (portfolio, brief, advisor, projection, scenario) shared/ db + utils apps/ cli/ mcp/ docs/ ``` **The rule:** external-API packages know nothing about firma's domain; domain packages know nothing about any external API. `@firma/adapters` is the single bridge. Adding a data source touches no command and no business logic — a new raw client, one adapter, one registration line. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full walkthrough and the recipe for adding a provider. ## Development Requires Node.js 22+ and Yarn Berry. ```bash corepack enable yarn install yarn dev:cli show portfolio # CLI dev mode yarn typecheck yarn test ``` --- ## Works with Herald firma is the financial-intelligence layer of the [Herald](https://ai-herald.vercel.app) ambient voice stack. Connected, Herald reports your net worth by voice, answers "how much did I spend on fees this quarter?" without a spreadsheet, and pulls market context mid-conversation. Herald + firma + [Memex](https://github.com/evan-moon/memex): ambient voice, financial intelligence, persistent memory — one personal AI stack. --- ## License MIT © [Evan Moon](https://github.com/evan-moon)