Finance Guru plugin
A personal family office in the terminal: typed portfolio calculators, a local ledger and agents for Claude Code and Codex.
- 333 ★ on the repository
- Last commit
- AGPL-3.0
Extended access
Why this level
- SnapTrade and SimpleFIN keys open read access to brokerage and bank data, and the settings holding them sit in the instance directory.
- Market, brokerage and model integrations send requests to configured providers, although storage stays local.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/finance-guruDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- SnapTrade and SimpleFIN keys open read access to brokerage and bank data, and the settings holding them sit in the instance directory.
- Market, brokerage and model integrations send requests to configured providers, although storage stays local.
This is third-party code. Review the repository files before installing.
What it does
Finance Guru is a plugin and engine for a self-hosted family office in Claude Code and Codex. Calculations are moved out of the model into 20 typed Python calculators with command-line interfaces: drawdown and VaR, momentum, volatility, correlation, optimization, backtesting, options, factors, hedging, total return and margin. The agent runs a calculator with the `--output json` flag and quotes the result without doing arithmetic itself. Skills and 11 specialist agents under an orchestrator work on top of the calculators. Private data sits in a separate directory outside the repository: a SQLite database, `.env` and broker CSV exports. Sync with SnapTrade and SimpleFIN uses your own read-only keys. Before a buy ticket draft is saved, guardrails check a 30% position cap and margin coverage of at least two, and block the ticket when data is missing.
Who it is for. Private investors with a brokerage account who keep records and analysis on their own computer and are comfortable in a terminal.
Good fit when
- You want VaR, CVaR, Sharpe ratio and drawdown for a ticker against a benchmark in one command.
- Broker CSV exports sit in a folder, and the agent has to combine positions, transactions and expenses in one database.
- A position keeps growing, and before buying you want to check the concentration limit and margin coverage.
- Once a week the margin rate in `.env` is compared with Fidelity's published table.
- Financial details are kept free of cloud dashboards, and bookkeeping stays on your machine.
Not a fit when
- You need an investment recommendation or a return forecast: the project says it gives no advice and promises no returns.
- Python 3.12 and uv are not installed and you prefer not to add them: the calculators run from a shell through uv.
- Your broker does not connect to SnapTrade, and CSV exports are inconvenient for you.
- Data must not leave for outside providers: market, brokerage and model integrations send requests to the services you pick.
Example request
Check whether the TSLA position is too large: run the metrics calculator over 252 days against SPY and quote the result.Limitations
Storage is local, but the network is not ruled out: market, brokerage and model integrations send data to the providers you configure. The engine needs Python 3.12 or newer, uv and Git, and Bun is needed for session hooks and the SimpleFIN sync app. Installing from a cloned repository is the fully supported path, and the plugin simplifies it. The license is AGPL-3.0. The swamp scheduler for the weekly margin rate check is marked experimental, and a failed check notifies no one. The project gives no financial advice.
How to disable. Remove the plugin with Claude Code's own tools or delete the repository clone. Private data sits in the instance directory, for example `~/finance-guru-data`, and is deleted by hand. A running scheduler is stopped with `swamp serve daemon disable`.
FAQ
How do I install Finance Guru as a Claude Code plugin?
Run `claude plugin marketplace add AojdevStudio/Finance-Guru`, then `claude plugin install finance-guru@finance-guru`, and start the `instance-onboarding` skill: it scaffolds the instance directory. Installing from a clone is fully supported too.
Do I need portfolio data to try it?
No. Market analysis works from a fresh clone: `uv run python -m src.analysis.risk_metrics_cli TSLA --days 252 --benchmark SPY` prints VaR, CVaR, Sharpe, Sortino, drawdown, volatility, beta and alpha from daily market data.
Where does my data go?
To an instance directory outside the repository: the `family_office.db` database, `.env`, broker exports and analysis outputs. Before a push, a hook scans history and the diff for secrets and personal data.
What happens when a check lacks data?
The guardrail blocks the ticket with a typed reason such as `equity_nav_unavailable` and writes nothing. It does not guess the missing value.
What is the buy ticket?
The model drafts a purchase idea and the system assembles trusted context: pre-borrow equity, the margin rate and a Layer 3 ITC score. If the checks pass, a draft is saved under a stable run id and a notification goes out.
Discussion
No questions or reviews yet.
Related
PluginsAnthropic's plugin marketplace for finance teams: 10 agents plus skills and MCP connectors for DCF and LBO models, earnings, reconciliation and KYC
Claude plugin for reading investor filings, sizing portfolio positions and preparing orders for a separate brokerage connector
Skill plugins for analyzing stocks, earnings, options and startups, plus readers for social feeds and market data
A Claude Code plugin for equity research reports: fundamental and technical analysis, scenarios and risk assessment, for education only
A financial analysis MCP server: 500+ methods from company statements, ratios, indicators, risk metrics and macro data
A set of skills for individual investors and traders: market review, stock screening, technical analysis, trade planning, journaling and post-trade review
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Finance Guru (this card) | no | 333 | ||
| Claude Trading Skills | no | 3,656 | a skill set for market overviews, screening and trade planning; Finance Guru adds tested calculators, a local ledger and guardrails | |
| The Finance Toolkit | yes | API key | 5,502 | an MCP server for financial analysis of company filings; Finance Guru works with your own portfolio and broker data in a local ledger |
README in short
The description is built on a split of roles: the agent drafts ideas, typed code computes, and guardrails refuse when data is missing. It includes architecture and ticket-check diagrams, the three-layer rule for every tool and a section of instructions for the agent itself. It closes with how the project began and a note that the commercial Keepfolio product runs on the same engine.