finance-guru

---

The Problem I Solved

I was drowning in complexity. Every investment decision meant:

• Opening Yahoo Finance for prices
• Switching to a spreadsheet for calculations
• Googling "how to calculate Sharpe ratio" (again)
• Copy-pasting data between 5 different tools
• Second-guessing myself because I couldn't see the full picture

The real cost wasn't time—it was confidence. I never felt certain my analysis was complete.

The Insight

What if instead of me becoming an expert in everything, I could have a team of experts who already knew my portfolio, my risk tolerance, and my goals?

Not a chatbot. Not an app. A personal family office that treats me like a wealth management client—but built on AI agents that can actually run calculations.

What I Built

Finance Guru™ is my private AI-powered family office. It's not software you install—it's a system where Claude transforms into specialized financial agents who work exclusively for me.

One command:

/finance-orchestrator

Eight specialists activate:

| Agent | Expertise | What They Do | |-------|-----------|--------------| | Cassandra Holt | Orchestrator | Coordinates the team, routes my requests | | Market Researcher | Intelligence | Scans markets, identifies opportunities | | Quant Analyst | Data Science | Runs calculations, builds models | | Strategy Advisor | Portfolio | Optimizes allocations, validates strategies | | Compliance Officer | Risk | Checks position limits, flags concerns | | Margin Specialist | Leverage | Analyzes margin strategies safely | | Dividend Specialist | Income | Optimizes yield, tracks distributions | | Tax Optimizer | Efficiency | Structures holdings for tax advantage |

See It In Action

Me: "Should I add more TSLA to my portfolio?"

What happens behind the scenes:

# Market Researcher checks momentum
uv run python src/utils/momentum_cli.py TSLA --days 90

# Quant Analyst calculates risk metrics
uv run python src/analysis/risk_metrics_cli.py TSLA --days 90 --benchmark SPY

# Quant Analyst checks market-implied risk
uv run python src/analysis/itc_risk_cli.py TSLA --universe tradfi

# Strategy Advisor checks correlation with existing holdings
uv run python src/analysis/correlation_cli.py TSLA PLTR NVDA --days 90

# Compliance Officer validates position size
# → Checks if addition exceeds concentration limits

What I get: A coordinated answer that considers momentum, risk, correlation, and compliance—not just a single data point.

The Technical Foundation

11 Production-Ready Analysis Tools

Every tool follows the same bulletproof pattern:

Pydantic Models → Calculator Classes → CLI Interfaces
     ↓                    ↓                  ↓
 Type Safety         Business Logic      Agent Access

| Category | Tools | Key Metrics | |----------|-------|-------------| | Risk | Risk Metrics, ITC Risk | VaR, CVaR, Sharpe, Sortino, Max Drawdown, Beta, Alpha | | Technical | Momentum, Moving Averages, Volatility | RSI, MACD, Golden Cross, Bollinger Bands, ATR | | Portfolio | Correlation, Optimizer, Backtester | Diversification score, Max Sharpe, Risk Parity | | Options | Options Pricer | Black-Scholes, Greeks, Implied Volatility |

External Risk Intelligence

ITC Risk Models API integration provides market-implied risk scores:

• Real-time risk assessment for TSLA, AAPL, MSTR, NFLX, SP500, commodities
• Risk bands help agents validate entry/exit timing
• Complements internal quant metrics with external perspective

Quick Start

For complete installation instructions, see docs/SETUP.md

Prerequisites

# Claude Code (the orchestration platform)
curl -fsSL https://claude.ai/install.sh | bash

# Python 3.12+ with uv package manager
curl -LsSf https://astral.sh/uv/install.sh | sh

# Bun (for onboarding and hooks)
curl -fsSL https://bun.sh/install | bash

# Docker (optional, for Google Drive MCP)
# Install from https://docs.docker.com/get-docker/

Setup

# 1. Fork and clone the repository
git clone https://github.com/YOUR-USERNAME/family-office.git
cd family-office

# 2. Run the setup script
./setup.sh

The setup script will:

• Create your private documentation directories
• Set up portfolio data folders
• Create user profile template
• Install Python dependencies
• Load Finance Guru agent commands (symlinks to ~/.claude/commands/fin-guru)
• Load Finance Guru skills (9 skills linked to ~/.claude/skills/)
• Run interactive onboarding wizard

Need help? See the complete setup guide for troubleshooting and configuration details.

What Gets Installed

The setup script symlinks Finance Guru components to your global Claude Code configuration:

Agent Commands (→ ~/.claude/commands/fin-guru/):

• /fin-guru:agents:finance-orchestrator - Main orchestrator (Cassandra Holt)
• /fin-guru:agents:market-researcher - Market intelligence specialist
• /fin-guru:agents:quant-analyst - Quantitative analysis specialist
• /fin-guru:agents:strategy-advisor - Portfolio strategy specialist
• /fin-guru:agents:compliance-officer - Risk and compliance specialist
• /fin-guru:agents:margin-specialist - Leverage analysis specialist
• /fin-guru:agents:dividend-specialist - Income optimization specialist
• /fin-guru:agents:onboarding-specialist - First-time setup guide

Skills (→ ~/.claude/skills/):

• fin-core - Core Finance Guru system context
• margin-management - Margin Dashboard integration
• PortfolioSyncing - Fidelity CSV → Google Sheets sync
• MonteCarlo - Monte Carlo simulation runner
• retirement-syncing - Retirement account sync (Vanguard/Fidelity)
• dividend-tracking - Dividend data sync
• FinanceReport - PDF analysis report generator
• TransactionSyncing - Transaction history import
• formula-protection - Spreadsheet formula protection

These symlinks allow you to use Finance Guru commands and skills from any Claude Code session.

Onboarding (First Time Users)

Important: Run the Onboarding Specialist before using Finance Guru.

# Start Claude Code in the project
claude

# Activate the Onboarding Specialist
/fin-guru:agents:onboarding-specialist

The Onboarding Specialist will guide you through:

1. Financial assessment questionnaire
2. Portfolio profile creation
3. Risk tolerance configuration
4. Strategy recommendations

After Onboarding

Once your profile is set up, activate the full Finance Guru system:

# Activate Finance Guru
/fin-guru:agents:finance-orchestrator

# Or go direct to a specialist
*quant            # "Analyze TSLA risk profile"
*strategy         # "Optimize my portfolio allocation"
*market-research  # "What's the momentum on NVDA?"

🍴 Fork Model: Use Finance Guru Safely

Finance Guru is designed to be forked and used privately. Here's how it works:

Architecture for Privacy

How to Use

1. Fork this repository to your GitHub account
2. Clone to your machine (never commit personal data)
3. Run onboarding to generate your private configs
4. Pull upstream updates safely (configs in .gitignore)

What's Tracked vs. Ignored

Tracked (safe to commit):

• ✅ Tools (src/, scripts/)
• ✅ Agent definitions (fin-guru/agents/)
• ✅ Templates (scripts/onboarding/modules/templates/)
• ✅ Documentation (docs/, README.md)
• ✅ Package files (pyproject.toml, package.json)

Ignored (private data):

• 🔒 fin-guru/data/user-profile.yaml (your financial data)
• 🔒 notebooks/updates/*.csv (your account exports)
• 🔒 .env (your API keys)
• 🔒 fin-guru-private/ (your private strategies)

Updating Your Fork

# Add upstream remote (one-time)
git remote add upstream https://github.com/ORIGINAL-AUTHOR/family-office.git

# Pull updates (safe - won't touch your private configs)
git fetch upstream
git merge upstream/main

# Your private data stays untouched

Security Checklist

Before pushing to GitHub:

# Verify private files are ignored
git status --ignored

# Ensure no sensitive data in commit
git diff --cached

# Check .env is ignored
ls -la .env  # Should show file exists locally
git check-ignore .env  # Should output ".env" (confirmed ignored)

Project Structure

family-office/
├── src/                      # Analysis engi