Skip to content
Back to search

finance-guru

MarketplaceWorks with Claude CodeGitHub

Install Finance Guru as a Claude Code plugin and scaffold an isolated local family-office instance.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/aojdevstudio/finance-guru with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/aojdevstudio/finance-guru'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aojdevstudio--finance-guru/badge.svg)](/listings/aojdevstudio--finance-guru)

HTML

<a href="/listings/aojdevstudio--finance-guru"><img src="/api/listings/aojdevstudio--finance-guru/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

[Python](https://www.python.org/) 3.12 or later, [uv](https://docs.astral.sh/uv/), and [Git](https://git-scm.com/). [Bun](https://bun.sh/) only if you work on the [SimpleFIN](https://www.simplefin.org/) sync app.

Install

git clone https://github.com/AojdevStudio/Finance-Guru.git
cd Finance-Guru
uv run python -m src.cli.instance_init ~/finance-guru-data --repo .

The instance is a small uv project outside the repo that depends on the engine. Private data lives there and nowhere else.

Run

cd ~/finance-guru-data
uv run python -m src.integrations.refresh_all --show
uv run python -m src.analysis.risk_metrics_cli TSLA --days 252 --benchmark SPY

The first command prints your position, transaction, and expense tables (empty on a new instance). Drop broker CSV exports into `imports/` to work CSV-first, or wire up [live sync](docs/setup/live-sync-credentials.md) later.

Install as a Claude Code plugin

claude plugin marketplace add AojdevStudio/Finance-Guru
claude plugin install finance-guru@finance-guru

Then run the `instance-onboarding` skill. It scaffolds the instance with `--plugin`, so the plugin is the single source of agents and skills and the checkout path's symlinks are skipped. The checkout path above remains the fully supported one.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 29 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://code.claude.com/schemas/marketplace.json",
  3. "name": "finance-guru",
  4. "owner": {
  5. "name": "AojdevStudio"
  6. },
  7. "description": "Install Finance Guru as a Claude Code plugin and scaffold an isolated local family-office instance.",
  8. "plugins": [
  9. {
  10. "name": "finance-guru",
  11. "source": ".",
  12. "description": "Private, self-hosted family-office workflows for research, quantitative analysis, portfolio strategy, and financial operations.",
  13. "author": {
  14. "name": "AojdevStudio"
  15. },
  16. "homepage": "https://github.com/AojdevStudio/Finance-Guru",
  17. "repository": "https://github.com/AojdevStudio/Finance-Guru",
  18. "license": "AGPL-3.0-only",
  19. "keywords": [
  20. "finance",
  21. "family-office",
  22. "portfolio",
  23. "investment-research",
  24. "quantitative-analysis",
  25. "self-hosted"
  26. ]
  27. }
  28. ]
  29. }
README.md · README · 373 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. <img src="docs/images/finance-guru-logo.png" alt="Finance Guru monogram" width="96">
  3. # Finance Guru
  4. ### **Your brokerage account is not a spreadsheet problem. It is an operating system problem.**
  5. _A self-hosted family office engine: typed Python calculators, a private SQLite ledger, and specialist agents that run inside Claude Code or Codex. Your data never leaves your machine unless you point it somewhere._
  6. <!--
  7. TODO: Replace docs/images/demo-risk-metrics.gif with a 20-30s demo clip.
  8. The clip should show Claude Code asking whether a position is too big, a calculator running, and a guardrail blocking.
  9. Keep this GIF until that clip exists.
  10. -->
  11. ![Terminal recording of the risk metrics CLI printing VaR, CVaR, Sharpe, Sortino, drawdown, volatility, beta, and alpha for TSLA against SPY](docs/images/demo-risk-metrics.gif)
  12. [![CI](https://github.com/AojdevStudio/Finance-Guru/actions/workflows/ci.yml/badge.svg)](https://github.com/AojdevStudio/Finance-Guru/actions/workflows/ci.yml)
  13. [![Quality gates](https://github.com/AojdevStudio/Finance-Guru/actions/workflows/quality-gates.yml/badge.svg)](https://github.com/AojdevStudio/Finance-Guru/actions/workflows/quality-gates.yml)
  14. [![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-3776AB?logo=python&logoColor=white)](pyproject.toml)
  15. [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
  16. [![GitHub stars](https://img.shields.io/github/stars/AojdevStudio/Finance-Guru?style=flat)](https://github.com/AojdevStudio/Finance-Guru/stargazers)
  17. [**Quick Start**](#quick-start) · [**How it works**](#how-it-works) · [**What's free**](#whats-free--licensing) · [**Docs**](https://aojdevstudio.github.io/Finance-Guru/) · [**For agents**](#if-you-are-an-agent)
  18. </div>
  19. One command, a full risk profile against live end-of-day data. No portfolio data required. Market analysis works from a fresh clone.
  20. ```bash
  21. uv run python -m src.analysis.risk_metrics_cli TSLA --days 252 --benchmark SPY
  22. ```
  23. ## The split
  24. You paste a screenshot into a chat model and ask whether a position is too big. The answer is plausible and unchecked. Chat models are excellent at deciding what question to ask and terrible at being the calculator. So split the job.
  25. <div align="center">
  26. ### **Agents propose. Typed code computes.**
  27. ### **Guardrails fail closed, in Python, with tests.**
  28. </div>
  29. _A self-hosted family office for $0._
  30. This is for a household that wants its books on its own machine: what you hold, the risk in it, and a check that refuses to guess when a number is missing. The software in this repository is free to clone and run. You bring a terminal, your own [Claude Code](https://code.claude.com/) or [Codex](https://github.com/openai/codex) session if you want the agents, and broker CSV exports you already have.
  31. _Not financial advice, and this project makes no return claims._
  32. Every number an agent quotes comes from a [Pydantic](https://docs.pydantic.dev/)-validated calculator with a CLI you can run yourself. Every irreversible action passes through a guardrail that blocks when its inputs are missing rather than guessing. The AI gets judgment. The math gets a test suite.
  33. <div align="center">
  34. ## **If a model can lie about it, a calculator owns it.**
  35. </div>
  36. ## Quick start
  37. ### Prerequisites
  38. [Python](https://www.python.org/) 3.12 or later, [uv](https://docs.astral.sh/uv/), and [Git](https://git-scm.com/). [Bun](https://bun.sh/) runs agent session hooks, repository PR gates, and the [SimpleFIN](https://www.simplefin.org/) sync app. The Python calculators run from a shell without Bun.
  39. ### Install
  40. ```bash
  41. git clone https://github.com/AojdevStudio/Finance-Guru.git
  42. cd Finance-Guru
  43. uv run python -m src.cli.instance_init ~/finance-guru-data --repo .
  44. ```
  45. The instance is a small uv project outside the repo that depends on the engine. Private data lives there and nowhere else.
  46. ### Run
  47. ```bash
  48. cd ~/finance-guru-data
  49. uv run python -m src.integrations.refresh_all --show
  50. uv run python -m src.analysis.risk_metrics_cli TSLA --days 252 --benchmark SPY
  51. ```
  52. The first command prints your position, transaction, and expense tables (empty on a new instance). Drop broker CSV exports into `imports/` to work CSV-first, or wire up [live sync](docs/setup/live-sync-credentials.md) later.
  53. ### Install as a Claude Code plugin
  54. ```bash
  55. claude plugin marketplace add AojdevStudio/Finance-Guru
  56. claude plugin install finance-guru@finance-guru
  57. ```
  58. Then run the `instance-onboarding` skill. It scaffolds the instance with `--plugin`, so the plugin is the single source of agents and skills and the checkout path's symlinks are skipped. The checkout path above remains the fully supported one.
  59. ## What is in the box
  60. Finance Guru is the open-core engine behind [Keepfolio](https://keepfolio.app/), a "claude-code for personal finance." This repo is the free, self-hosted, CLI-native experience: the whole engine, every skill, every agent, no withheld tier.
  61. | Component | What it does | Why it matters |
  62. | :--- | :--- | :--- |
  63. | **Typed calculators** (`src/`) | 20 CLIs for risk, momentum, volatility, correlation, optimization, backtesting, options, factors, hedging, total return, and margin metrics. Every one is Pydantic input, calculator class, CLI wrapper. | Calculations are testable outside any AI session. The suite is 1,100+ tests behind an 80% coverage gate. |
  64. | **Private instance** | A directory outside the repo holding `family_office.db`, your `.env`, broker CSVs, and every artifact the engine writes. | No spreadsheet, no cloud sync, no vendor dashboard between you and your ledger. Tracked files never carry personal values. |
  65. | **Sync layer** (`src/integrations/`) | `refresh_all` pulls [SnapTrade](https://snaptrade.com/) (brokerage) and SimpleFIN (bank and card) into [SQLite](https://www.sqlite.org/) with your own read-only credentials. | Partial provider responses raise before any write. You get an error instead of a coverage ratio computed on half your accounts. |
  66. | **Fail-closed guardrails** | Concentration cap, margin coverage, and ITC risk run against trusted inputs before a buy ticket persists. | A block on missing NAV, missing rate, or an unrun Layer 3 score. A bad ticket needs a number to pass, not a prompt to agree. |
  67. | **Skills and specialists** (`.claude/`) | Skills and 11 specialist agents coordinated by a finance orchestrator. They read the DB, run the CLIs, and write Markdown into your instance. | Every output carries its data source, date stamp, and the educational-only disclaimer. You can trace any claim back to a CLI run. |
  68. | **Compliance scan on push** | A pre-push hook scans history and the diff for secrets and PII. | The repo is public. Your data is not. The hook is what keeps that true. |
  69. ![Finance Guru architecture: providers sync through refresh_all into a private SQLite instance, typed calculators read the store and market data, skills and specialists drive the calculators from Claude Code or Codex, and artifacts land back in the instance.](docs/images/architecture.png)
  70. ## How it works
  71. ### The guardrail loop
  72. The buy-ticket pipeline is the clearest example of the split between judgment and arithmetic.
  73. ![Buy-ticket guardrail flowchart: a settled deposit triggers a model proposal, trusted context is assembled from equity NAV, the margin rate, and Layer 3 ITC risk, and the guardrail either blocks with a typed reason or persists a draft and notifies, with retries reusing the draft.](docs/images/guardrails.png)
  74. The model drafts a proposal. It has no say over the inputs that judge it. `GuardrailContext` carries the pre-borrow equity NAV, the configured annual margin rate, and the Layer 3 ITC score, and the checks run against those:
  75. ```python
  76. CONCENTRATION_LIMIT = 0.30 # of pre-borrow equity NAV, never of a margin-inflated total
  77. MIN_MARGIN_COVERAGE = 2.0 # dividend income over projected interest, new borrowing included
  78. MAX_ITC_RISK = 0.7 # from Layer 3 output only; missing, not-run, or failed blocks
  79. ```
  80. A block returns a typed reason (`equity_nav_unavailable`, `margin_rate_unavailable`, `coverage<2x`) and writes nothing. A pass persists the draft under a stable run id, then notifies. A failed notification is its own outcome, so a retry reuses the draft instead of writing a second one.
  81. ### The three-layer pattern
  82. ```text
  83. src/analysis/risk_metrics.py Pydantic input model + RiskCalculator
  84. src/analysis/risk_metrics_cli.py argparse wrapper, --output json, disclaimer
  85. tests/python/test_risk_metrics.py the math, tested without a network
  86. ```
  87. Every tool in the engine follows this shape, so an agent can only ever call a CLI and quote its output. Nineteen of the twenty CLIs take `--output json`; margin metrics prints JSON by default. That is the contract the skills consume, so what an agent reports is exactly what the calculator returned. See the [CLI reference](docs/reference/api.md) for all 20.
  88. ```bash
  89. uv run python -m src.analysis.risk_metrics_cli TSLA --days 252 --benchmark SPY --output json
  90. ```
  91. ### The private instance
  92. The engine reads every private file from an instance directory outside the repository, resolved from `FIN_GURU_DATA_ROOT` or the current working directory. The instance holds `.env`, `user-profile.yaml`, `config.yaml`, `family_office.db`, `snaptrade-accounts.yaml`, and the working directories `imports/`, `analysis/`, `tickets/`, `strategies/`, `hedging/`, `reports/`, `auto-tickets/`, and `notes/`. Tracked files describe behaviour and never carry personal values. The full rule and its enforcement live in [DataClassification](.claude/skills/compliance-scan/references/DataClassification.md) and [PRIVACY.md](PRIVACY.md).
  93. Local-first does not mean network-free. Market data, brokerage, and LLM integrations send request data to their configured providers. Configure only the integrations you intend to use.
  94. ### Scheduled checks with swamp
  95. [swamp](https://github.com/swamp-club/swamp) (Swamp Club) runs Finance Guru's scheduled checks. The engine computes the numbers. swamp runs checks on a timer, compares those numbers with outside sources, and keeps a record of every run. Everything lives in this repository under `automations/swamp/`, and swamp's own service runs the schedule, so no other tool is needed.
  96. Words used below:
  97. - A _behavior_ is a small TypeScript program with named methods. `fidelity-margin-rate` is one.
  98. - A _workflow_ is a YAML file that runs behavior methods in order. `margin-rate-check` is one.
  99. - `swamp serve` is swamp's long-running process. It fires every workflow that has a `trigger.schedule`.
  100. **The margin-rate check.** [Fidelity](https://www.fidelity.com/) charges a margin rate that depends on the size of your debt. The `margin-rate-check` workflow catches a rate in your `.env` that no longer matches:
  101. 1. `refresh` runs the engine's SnapTrade positions sync in your instance, so the margin debt in `family_office.db` is current.
  102. 2. `check` asks the engine's `margin_metrics_cli` for your margin debt and configured rate (`FG_MARGIN_INTEREST_RATE_DECIMAL`), reads [Fidelity](https://www.fidelity.com/)'s published rate table, and compares the rate for that debt with yours. A mismatch fails the run. The check never edits your `.env`.
  103. It runs Mondays at 9:15 in the machine's local time zone. On a machine set to US Central time, that is after SnapTrade's daily holdings sync, about 8:45 AM CT.
  104. #### What you need
  105. - A Finance Guru checkout and an instance with a Fidelity margin account routed as `taxable_margin` in `snaptrade-accounts.yaml`.
  106. - `FG_MARGIN_INTEREST_RATE_DECIMAL` and `FG_MARGIN_JUMP_ALERT_THRESHOLD` set in the instance `.env`. The engine's `margin_metrics_cli` needs both.
  107. - `uv` on the machine.
  108. - The swamp CLI, installed as its [README](https://github.com/swamp-club/swamp) describes, and signed in with `swamp auth login`. Every swamp process, the service included, needs that sign-in to start.
  109. #### Configure the check
  110. Create the behavior definition once. It records your instance path and the full path to `uv`, so it stays on your machine: `automations/swamp/.gitignore` ignores `models/`.
  111. ```bash
  112. cd automations/swamp
  113. swamp behavior create @aojdevstudio/fidelity-margin-rate fidelity-margin-rate \
  114. --global-arg instanceDir=/path/to/your/instance \
  115. --global-arg uvPath="$(command -v uv)"
  116. swamp workflow validate margin-rate-check
  117. ```
  118. The service starts with a minimal `PATH` and without your shell's variables, so give full paths here, not `FIN_GURU_DATA_ROOT`.
  119. #### Run it by hand
  120. ```bash
  121. cd automations/swamp
  122. swamp workflow run margin-rate-check --json
  123. swamp data query 'behavior("fidelity-margin-rate") && name == "rate"' --select content --json
  124. ```
  125. The last command prints the newest comparison: tier rate, configured rate, margin debt, and `drift`. To check the rate without syncing first, run `swamp behavior run fidelity-margin-rate check`. It refuses a ledger synced more than 24 hours ago.
  126. Run the tests with the Deno that ships with swamp (`swamp doctor extensions --json` prints its path as `denoPath`):
  127. ```bash
  128. ~/.swamp/deno/deno test --allow-read extensions/behaviors/
  129. ```
  130. #### Start the service
  131. swamp installs `swamp serve` as a per-user service: a launchd agent on macOS, a systemd user unit on Linux. The command is marked experimental in swamp's help.
  132. ```bash
  133. cd automations/swamp
  134. swamp serve daemon enable --user --repo-dir "$PWD" --host 127.0.0.1 --port 9093
  135. swamp serve daemon status
  136. curl -s http://127.0.0.1:9093/health
  137. ```
  138. `/health` lists each schedule with its `nextRun` in UTC. Check that the margin-rate and hedge-trigger checks appear there. Stop the service with `swamp serve daemon disable`.
  139. - The service loads the behavior code once, at start. After you pull changes under `automations/swamp/extensions/`, run the `daemon enable` command again to restart it. Until then, scheduled runs use the old code. Workflow and schedule edits take effect without a restart.
  140. - swamp installs one serve service per user, so `daemon enable` here replaces a serve service you already run for another repository. The check needs this layout: the workflow, the behavior, and your local definition all in `automations/swamp/` inside a Finance Guru checkout, because the behavior finds the engine two folders up.
  141. - On Linux, a user unit stops when you log out unless lingering is on: `loginctl enable-linger "$USER"`.
  142. - A schedule missed while the machine was asleep or off does not run later. Run the workflow by hand when that happens.
  143. #### Where results and logs go
  144. - Run history: `swamp workflow history search --json`. A scheduled run shows `"triggerSource": "schedule"`.
  145. - The latest comparison: the `swamp data query` command above.
  146. - Why a run failed: `swamp report get @swamp/workflow-summary --workflow margin-rate-check --json`.
  147. - Service logs: `~/Library/Logs/swamp/serve.stdout.log` and `serve.stderr.log` on macOS, `journalctl --user -u swamp-serve` on Linux.
  148. - Run data lives in `automations/swamp/.swamp/`, which git ignores.
  149. A failed run notifies no one. Check the history, or point a tool you already use at it.
  150. **How it relates to the stale-equity guard.** The engine computes margin debt as gross market value minus SnapTrade's account equity, and the equity is only as fresh as SnapTrade's last holdings sync ([#259](https://github.com/AojdevStudio/Finance-Guru/issues/259)). The engine refuses equity over 12 hours old with `StaleAccountEquityError`, and the ledger stores an empty margin debt instead of a wrong one ([#260](https://github.com/AojdevStudio/Finance-Guru/pull/260)). The rate check reads the debt through the engine, so it fails on an empty debt too, and it refuses a ledger synced more than 24 hours ago. It reads that time from `ledger_synced_at` in the engine's output. Stale data never picks a rate tier. The engine guard stops wrong numbers before they exist. The swamp check catches settings that have drifted from the broker.
  151. **The hedge-trigger check.** The `hedge-trigger-check` workflow suggests when to start or exit a triggered inverse-ETF hedge. It suggests only. It never trades or moves money. It runs weekdays at 16:30 in the machine's local time zone, which on a US Central machine is after the US close and after SnapTrade's morning sync.
  152. 1. `refresh` runs the same SnapTrade positions sync as the margin-rate check. If the sync fails, the check still runs and reports the stale input.
  153. 2. `activity` runs the SnapTrade activities sync, so a held hedge's entry date comes from current history. Activity that does not add up to the held shares gives `NO_VERDICT`.
  154. 3. `check` runs `src.analysis.hedge_trigger_cli --output json`. The engine reads your thresholds from the `hedge_triggers:` section of `user-profile.yaml`, margin numbers from the ledger, your hedge position and its entry date from the ledger, and daily closes from [yfinance](https://github.com/ranaroussi/yfinance). It returns one action: `START` with a size, `HOLD`, `EXIT` with the rules that fired, or `NO_VERDICT` naming the input that was stale or missing.
  155. Holdings/debt in these rules is gross holdings (account equity plus margin debt) divided by margin debt. `margin_metrics_cli` reports equity/debt as `portfolio_margin_ratio`, which is a different number.
  156. The check writes every suggestion as a versioned record. It fails the run when the suggestion is `START` or `EXIT`, or differs from the last one, so those days show as red runs, like a margin-rate drift. A missing `hedge_triggers:` section fails the run with no record. Every key is required, and the engine has no defaults for them:
  157. ```yaml
  158. hedge_triggers:
  159. hedge_symbol: "SQQQ"
  160. index_symbol: "QQQ"
  161. volatility_symbol: "^VIX"
  162. moving_average_days: 50
  163. start_ratio_below: 3.0 # holdings/debt
  164. start_drawdown_at_least: 0.10 # below the 52-week high, and below the average
  165. start_volatility_at_least: 25
  166. exit_gain_at_least: 0.30 # alone, this exits half
  167. exit_within_high: 0.05
  168. exit_closes_above_average: 3
  169. exit_ratio_above: 3.5
  170. exit_after_days: 30
  171. max_size_of_holdings: 0.06
  172. ```
  173. Create its behavior definition, then run it and read the newest suggestion:
  174. ```bash
  175. cd automations/swamp
  176. swamp behavior create @aojdevstudio/hedge-trigger hedge-trigger \
  177. --global-arg instanceDir=/path/to/your/instance \
  178. --global-arg uvPath="$(command -v uv)"
  179. swamp workflow validate hedge-trigger-check
  180. swamp workflow run hedge-trigger-check --json
  181. swamp data query 'behavior("hedge-trigger") && name == "hedge"' --select content --json
  182. ```
  183. The workflow's `refresh` step uses the `fidelity-margin-rate` definition, so create that one too.
  184. ## If you are an agent
  185. You are the intended operator of this engine, not an afterthought. A few things that make you effective here:
  186. - **Read your instance's `AGENTS.md` first.** It points to the canonical finance context and skill tree. [Codex](https://github.com/openai/codex) discovers those skills through the instance's `.agents` symlink. Repository developer instructions stay in the engine checkout.
  187. - **Run `date` before any market work.** Every specialist here is expected to know the current date before it searches or analyzes.
  188. - **Never do the arithmetic yourself.** Call the CLI with `--output json` and quote what it returned. That is the whole reason the calculators exist.
  189. - **Private data lives in the instance, not the repo.** Resolve `FIN_GURU_DATA_ROOT` or the working directory, read from `family_office.db`, and write artifacts into `analysis/` or `tickets/`. Tracked files never carry personal values, and the pre-push scan will stop you if you try.
  190. - **Every financial output carries the educational-only disclaimer,** a date stamp, and its data source. The CLIs print it; the skills expect it.
  191. - **Fail closed.** If a guardrail input is missing, the answer is a block with a typed reason. Do not fill the gap with an estimate.
  192. - **Contributing a tool means all three layers.** Pydantic input model, calculator class, CLI wrapper, plus a test that runs without a network.
  193. Skills in `.claude/skills/` are the workflows; specialists in `.claude/agents/` are the subagents; the finance orchestrator is the main session and routes between them.
  194. ## Why this exists
  195. Finance Guru started as one operator's answer to a personal constraint. Its author spent over a decade in pharmacy operations before teaching himself to build software, and along the way stopped using a checking account at all. Everything ran through a brokerage: paychecks in, margin as operating capital, dividends as the second income layer. No consumer finance app models that. They all assume a bank.
  196. The stopgap was a chat model and a habit of pasting screenshots into it. Every answer was plausible. None of it was checked. The model did the arithmetic in its head, the positions lived in a CSV exported three weeks earlier, and the guardrail that should have stopped a bad ticket was a sentence in a prompt, not a line of code. Nothing was repeatable, so nothing was auditable.
  197. > _"A fully autonomous, unbiased family office with agentic personalities grounded in math and truth, helping me achieve financial freedom."_
  198. > The vision statement in [docs/VISION.md](docs/VISION.md), March 2026.
  199. The first commits were agent personas and prompts. Persuasive, and unverifiable. The fix was not a better prompt. It was moving every calculation into typed Python with a CLI, so the agent's only move is to run the tool and read the answer. That split, judgment in the agent and arithmetic in code, is the whole architecture.
  200. The second lesson came from sync. SimpleFIN can return HTTP 200 with a dropped account buried in an `errors` array, and the sync used to count that and move on. Now the rule is that anything financial fails loud or fails closed. Missing data blocks. Partial data raises. A guardrail without its inputs is a block, not a pass.
  201. The repo is public because the pattern is more useful than the portfolio. The commercial macOS product, Keepfolio, is built on this engine. The engine stays free and complete.
  202. <div align="center">
  203. ### The artifacts are the argument.
  204. </div>
  205. ## Roadmap
  206. - [x] Three-layer calculators for risk, momentum, volatility, correlation, optimization, backtesting, options, factors, hedging, and margin
  207. - [x] Local SQLite system of record fed by SnapTrade and SimpleFIN
  208. - [x] Fail-closed buy-ticket guardrails with Layer 3 ITC authority
  209. - [x] [Diátaxis](https://diataxis.fr/) documentation site on [GitHub Pages](https://pages.github.com/)
  210. - [ ] [Claude Code](https://code.claude.com/) plugin as the primary install path ([#131](https://github.com/AojdevStudio/Finance-Guru/issues/131))
  211. - [ ] Retirement-account sync migration gate ([#74](https://github.com/AojdevStudio/Finance-Guru/issues/74))
  212. - [ ] Automated releases through [release-please](https://github.com/googleapis/release-please) ([#112](https://github.com/AojdevStudio/Finance-Guru/issues/112))
  213. Open items carry the `roadmap` label. Defects carry `bug`.
  214. Recent changes are in the [changelog](CHANGELOG.md).
  215. ## Contributing
  216. Read [Contributing](docs/CONTRIBUTING.md) first. It covers the accepted surfaces, the quality gates, and the privacy rules every push must pass. The required Python gates mirror CI:
  217. ```bash
  218. uv sync --dev
  219. uv run ruff format --check .
  220. uv run ruff check .
  221. uv run mypy src/
  222. uv run pytest -m "not integration"
  223. ```
  224. ## Documentation
  225. | Document | Purpose |
  226. | --- | --- |
  227. | [Documentation site](https://aojdevstudio.github.io/Finance-Guru/) | Tutorials, how-to guides, reference, and explanation |
  228. | [Setup](docs/setup/SETUP.md) | Install the engine and create an instance |
  229. | [CLI reference](docs/reference/api.md) | Commands, arguments, and output |
  230. | [Live sync credentials](docs/setup/live-sync-credentials.md) | Bring-your-own-credentials setup for SnapTrade and SimpleFIN |
  231. | [Runbooks](docs/runbooks/README.md) | Recurring portfolio and operations workflows |
  232. | [Troubleshooting](docs/setup/TROUBLESHOOTING.md) | Common installation and runtime failures |
  233. ## Acknowledgments
  234. Market data through [yfinance](https://github.com/ranaroussi/yfinance). Brokerage connectivity through [SnapTrade](https://snaptrade.com/). Bank and card connectivity through [SimpleFIN](https://www.simplefin.org/). Agent surfaces on [Claude Code](https://code.claude.com/) and [Codex](https://github.com/openai/codex). Diagrams drawn with the diagram-design skill; terminal recording with [vhs](https://github.com/charmbracelet/vhs).
  235. ## What's free / licensing
  236. Everything tracked in this repository is free under the [GNU Affero General Public License v3.0](LICENSE), or, at your option, any later version. That covers the Python calculators, the ledger code, the skills, the specialist agents, the docs, and the apps. There is no paid tier here, and no feature of this engine is held back. You can run it, change it, and share it. If you run a modified version as a network service, the license requires you to offer that version's source to the people who use it.
  237. [Keepfolio](https://keepfolio.app/) is a separate commercial macOS product built on this engine. Its source is not in this repository, and this repository does not state Keepfolio's license. This repo is the free terminal-native engine. Keepfolio is the polished app for someone who will not run one.
  238. The copyright notice and the same split are in [LICENSING.md](LICENSING.md).
  239. ## License
  240. Finance Guru is licensed under the [GNU Affero General Public License v3.0](LICENSE), or any later version. See [LICENSING.md](LICENSING.md).
  241. ## Financial disclaimer
  242. Not financial advice, and this project makes no return claims. Finance Guru is educational software. Financial markets involve risk, including possible loss of principal. Verify all data and calculations independently and consult appropriately licensed financial, tax, and legal professionals before acting.
  243. ---
  244. <div align="center">
  245. **Agents propose. Typed code computes.**
  246. If the split between judgment and arithmetic is the thing you were missing, [star the repo](https://github.com/AojdevStudio/Finance-Guru).
  247. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.