Hedge FFFund

An AI-native investment research workspace powered by Claude Code. Files are the database, Markdown is the schema, and Claude Code skills are the workflows.

This is a decision support system, not an autonomous trader. Every analysis, signal, and strategy proposal is designed for a human to review and act on.

How It Works

The workspace is structured around a simple loop: research → thesis → strategy → decision.

1. Research a ticker (/research AAPL) — pulls live data via MCP servers (yfinance, OpenInsider, SEC EDGAR) and writes a structured universe file.
2. Build a thesis — write or refine investment theses in theses/ that span multiple tickers.
3. Get strategy proposals (/advise VRT) — generates trackable trade strategies (equity, options, pairs) with real entry/stop/target levels.
4. Track positions (/mark) — marks open strategies to market with P&L, alerts on stops/targets hit.
5. Log decisions (/decision VRT buy) — creates an audit trail with reasoning, metrics, and review dates.
6. Scan for signals (/scan premarket or /scan postmarket) — daily reports covering price action, insider trades, analyst moves, sentiment, and thesis status across your watchlist.

All data lives in plain Markdown files you can read, edit, and version-control.

Project Structure

universe/       # One file per ticker — facts, financials, key metrics
theses/         # Investment theses spanning tickers — arguments, risks, catalysts
strategies/     # Proposed trade strategies with mark-to-market tracking
decisions/      # Buy/sell/hold log with dated reasoning (audit trail)
signals/        # Daily pre-market and post-market scan reports
portfolio/      # Current holdings and allocations
data/           # Raw data dumps from MCP sources
scripts/        # Automation (daily scan runner, launchd plists)
.claude/skills/ # Claude Code skill definitions (the /commands)

Skills (Slash Commands)

Run these inside a Claude Code session in this project directory:

Command	What it does
/research <TICKER>	Quick research pass — pulls data, creates/updates universe/<TICKER>.md
/deepdive <TICKER>	Institutional-grade deep dive — bull/bear cases, valuation, technicals, strategy proposals
/compare <T1> <T2> [T3...]	Side-by-side comparison table across key metrics
/advise <TICKER>	Proposes 1-3 trackable strategies (equity, options, pairs) with live pricing
/mark [TICKER]	Marks open strategies to market — updates P&L, flags stop/target alerts
/decision <TICKER> <buy|sell|hold|trim|add>	Logs a decision with structured reasoning to decisions/
/scan <premarket|postmarket>	Daily signal scan — watchlist quotes, insider trades, analyst actions, thesis tracking

Setup

Prerequisites

• Claude Code CLI installed and authenticated
• Node.js (for npx-based MCP servers)
• uv (for uvx-based MCP servers)

1. Clone and enter the repo

git clone <repo-url>
cd hedge-fffund

2. Configure MCP servers

The .mcp.json file at the repo root defines four data sources that Claude Code will use:

Server	Transport	What it provides	Auth
yfinance	uvx yfinance-mcp-server	Prices, volume, financials, analyst data, options, earnings	None
OpenInsider	npx openinsider-mcp	Insider trades, SEC filings, short interest, FTD data	None
Financial Datasets (optional)	uv run (local clone)	Income statements, balance sheets, cash flow, news	API key required
SEC EDGAR	uvx sec-edgar-mcp	Direct 10-K/10-Q/8-K filing access	User-agent string

yfinance and OpenInsider work out of the box with no configuration. SEC EDGAR just needs a user-agent string. Financial Datasets is optional — if you want it, copy the env template and fill in your keys:

cp scripts/.env.example ~/.investor-env

Edit ~/.investor-env:

FINANCIAL_DATASETS_API_KEY=your_key_here
FINANCIAL_DATASETS_MCP_DIR=/path/to/cloned/financial-datasets-mcp-server
# SEC_EDGAR_UA="your-name your-email@example.com"

3. Start using it

cd hedge-fffund
claude   # launches Claude Code in this directory

Then run any skill:

/research VRT
/scan premarket
/advise AAPL

4. (Optional) Automated daily scans

The repo includes a shell script that runs scans headlessly via claude -p:

# Manual run
./scripts/daily-scan.sh premarket
./scripts/daily-scan.sh postmarket

To automate on macOS with launchd, create plist files in ~/Library/LaunchAgents/ that call the script at your preferred times (e.g., 7:00 AM for premarket, 5:00 PM for postmarket). Then:

launchctl load ~/Library/LaunchAgents/com.investor.scan-premarket.plist
launchctl load ~/Library/LaunchAgents/com.investor.scan-postmarket.plist

Scans use the Sonnet model.

Extending It

Add a new ticker to the watchlist

Edit CLAUDE.md and add the ticker under the appropriate tier in ## Current Watchlist. Then run /research <TICKER> to populate its universe file.

Write a new thesis

Create a file in theses/ with a descriptive name (e.g., theses/semiconductor-reshoring.md). Reference tickers with [[TICKER]] notation. The /scan postmarket report will automatically track thesis status.

Add a new MCP data source

1. Add the server config to .mcp.json
2. Add the server name to .claude/settings.local.json under enabledMcpjsonServers
3. Update relevant skill files in .claude/skills/ to use the new tools

Create a new skill

1. Create a directory under .claude/skills/<skill-name>/
2. Add a SKILL.md file with frontmatter (name, description, arguments, allowed-tools) and the prompt template
3. The skill becomes available as /<skill-name> in Claude Code sessions

Look at .claude/skills/research/SKILL.md for a simple example, or .claude/skills/scan/SKILL.md for a complex one.

Conventions

• Universe files: universe/{TICKER}.md — facts, not opinions
• Thesis files: theses/{descriptive-name}.md — arguments and analysis
• Strategy files: strategies/{TICKER}-{slug}.md — trackable trade proposals
• Decision files: decisions/{YYYY-MM-DD}-{TICKER}-{action}.md — audit trail
• Signal files: signals/{YYYY-MM-DD}-{premarket|postmarket}.md — daily reports
• Cross-reference between files using [[TICKER]] notation
• Always note the date of data sources — flag anything older than 30 days as stale

Disclaimer

This is a personal research tool, not financial advice. All investment decisions are your own.