dokson/hedge-fund-tracker
dokson/hedge-fund-tracker has 83 GitHub stars and 23 forks. GitHot measured +1 stars in 24 hours, +1 in 7 days, and +3 in 15 days. Last checked 2026-11-15 14:27 UTC. Last push 2026-11-04.
What you can do
- π Web UI - Research-first React interface with an editorial landing page, compact filing register, familiar tables and charts, light/dark themes, and SSE streaming for long-running AI tasks.
- π Visual Analytics - Interactive charts (Recharts) to track institutional holdings, sectoral trends, and quarterly portfolio evolutions.
- π Comparative Analysis - Combines quarterly (13F) and non-quarterly (13D/G, Form 4) filings for an up-to-date view.
- π Fund & Stock Pages - Per-fund portfolio pages (holdings, weights, quarter-over-quarter deltas, composition by stock and by sector) and per-ticker analysis pages (which tracked funds own it and how their conviction is shifting).
Measured star growth
- in 24h
- +1
- in 7 days
- +1
- in 15 days
- +3
- in 1 month
- Update delayed
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
π Hedge Fund Tracker: Track SEC 13F/13D filings with AI-Powered Insights for Stock Investments
Web & AppsREADME.md
Original![]()
π Hedge Fund Tracker
If this tool is helping you, please β the repo! It really helps discoverability.
SEC 13F Filing Tracker | Institutional Portfolio Analysis | AI-Powered Stock Research
A comprehensive Python tool for tracking hedge fund portfolios through SEC filings (13F, 13D/G, Form 4). Transform raw SEC EDGAR data into actionable investment insights. Built for financial analysts, quantitative traders, and retail investors seeking to analyze institutional investor strategies, portfolio changes, and discover stock opportunities by following elite fund managers.
β«Άβ° Table of Contents
- π Hedge Fund Tracker
- β«Άβ° Table of Contents
- π Quick Start
- β¨ Key Features
- π¦ Installation
- π Project Structure
- π¨π»βπ» How This Tool Tracks Hedge Funds
- π’ Hedge Funds Selection
- π§ AI Models Selection
- β οΈ Limitations & Considerations
- π³ Docker Deployment
- π GitHub Pages Deployment
- βοΈ Automation with GitHub Actions
- ποΈ Technical Stack
- π€πΌ Contributing & Support
- π References
- ππΌ Acknowledgments
- π License
- β Star History
π Quick Start
# Clone the repository
git clone https://github.com/dokson/hedge-fund-tracker.git
cd hedge-fund-tracker
# Install Python dependencies
pipenv install
# Install and build the React frontend
pipenv run build-frontend
# Run the application (opens web UI in your browser)
pipenv run app
π³ Or use Docker (no local build required)
python scripts/generate_secrets.py --write # creates .env with freshly generated secrets
docker compose up --build
docker compose starts the app and a Postgres container. The required secrets
(POSTGRES_PASSWORD, MASTER_KEY, RESET_PASSWORD_TOKEN_SECRET, VERIFICATION_TOKEN_SECRET) have
no defaults: if any of them is missing, docker compose up aborts instead of starting. Optional API
keys can be copied into the same .env from .env.example.
The app will be available at http://localhost:8000.
β¨ Key Features
| Feature | Description |
|---|---|
| π Web UI | Research-first React interface with an editorial landing page, compact filing register, familiar tables and charts, light/dark themes, and SSE streaming for long-running AI tasks. |
| π Visual Analytics | Interactive charts (Recharts) to track institutional holdings, sectoral trends, and quarterly portfolio evolutions. |
| π Comparative Analysis | Combines quarterly (13F) and non-quarterly (13D/G, Form 4) filings for an up-to-date view. |
| π Fund & Stock Pages | Per-fund portfolio pages (holdings, weights, quarter-over-quarter deltas, composition by stock and by sector) and per-ticker analysis pages (which tracked funds own it and how their conviction is shifting). |
| π Smart Ticker Resolution | Multi-fallback system (yfinance β OpenFIGI β TradingView) resolves CUSIPs into actionable stock symbols, with company-rename handling via TradingView's name-search fallback. Form 4 reverse lookups (ticker β CUSIP) go through Financial Modeling Prep. |
| π€ AI Financial Analyst | An LLM ranks stocks by "Promise Score" from the institutional filing data (how many tracked funds hold a stock, how large the positions are, how they changed) and writes a due-diligence report on a single ticker. |
| βοΈ Automated Data Pipeline | Scheduled GitHub Actions to fetch, process, and commit the latest SEC filings directly to your repository. |
| π GitHub Pages Demo | Static deployment with bundled data β all analysis features work without a backend. |
| β Personalized Watchlist | Star your favorite funds or stocks for quick access and personalized tracking across the platform. |
| π·οΈ Sector & Industry | Every stock is auto-tagged with Yahoo Finance industry; sector is derived via sector_hierarchy.csv. ETFs share a single "ETF" bucket. New tickers run through a yfinance β same-Company match β Groq LLM fallback chain. |
| π Global Search | Top-bar search across tickers, companies, fund names and managers, with grouped results, keyboard navigation (βK) and company logos inline. |
| πΌοΈ Company Logos | Logos served via Cloudinary's edge CDN, sourced lazily from Financial Modeling Prep, shown in a dedicated 32px slot on a white or dark plate chosen from the artwork so light marks stay visible. |
The navigation's 13F baseline labels the newest usable quarterly snapshot, not the freshness of every price or disclosure. Latest Filings filters and orders the latest saved position disclosures by publication date, shows their separate position dates, and labels each reference price as a historical market-price estimate rather than a fund's cost basis. Smart Score is a relative institutional screen, not a return forecast; its Momentum component measures net fund buying, not price momentum. Strategy and fund-return pages show sample and coverage limits before their results; fund returns estimate reported 13F holdings, not certified manager performance. Research context is kept for the session: filters, sorting and list position survive opening a stock or fund and coming back, while explicit URL parameters still win.
π¦ Installation
Prerequisites
- Python 3.14+
- Node.js 24+ (for the React frontend)
- pipenv (install with
pip install pipenv)
π₯ Clone and navigate:
git clone https://github.com/dokson/hedge-fund-tracker.git cd hedge-fund-trackerπ² Install dependencies: Navigate to the project root and run the following command. This will create a virtual environment and install all required packages.
pipenv installπ‘ Tip: If
pipenvis not found, you might need to usepython -m pipenv install. This can happen if the user scripts directory is not in your system's PATH.π¨ Build the frontend: Build the React interface (required once before first run):
pipenv run build-frontendβΆοΈ Run the application: Execute within the project's virtual environment:
pipenv run appThis starts a FastAPI server (default
http://localhost:8000, auto-increments if port is busy) and opens the web UI in your browser automatically.β οΈ Note on CLI mode (Legacy): The terminal CLI is a deprecated version of the tool, built before the development of the Web UI. While still functional, it reads its API keys from a
.envfile, which the Web UI writes for you the first time you save a key on the AI Settings page (or you can create it yourself from.env.example). So, if you still wish to use the "old school" CLI, just run:pipenv run app-cli
Data Management
The data update operations (downloading and processing filings) are inside a dedicated script. This keeps the main application focused on analysis, while the updater handles populating and refreshing the database.
To run the data update operations, you need to use the updater.py script from the project root:
pipenv run python -m database.updater
Database Updater
The updater.py script includes semi-automated maintenance tasks:
- Sorting: Upon exit (option
0), the script automatically sorts thedatabase/stocks.csvfile by ticker to maintain performance and prevent Git diff noise. - Auto-Documentation: This README's excluded funds section is synchronized whenever the database is refreshed manually.
This will open a separate menu for data management:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Hedge Fund Tracker - Database Updater β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 0. Exit β
β 1. Generate latest 13F reports for all known hedge funds β
β 2. Fetch latest non-quarterly filings for all known hedge funds β
β 3. Generate 13F report for a known hedge fund β
β 4. Manually enter a hedge fund CIK to generate a 13F report β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
API Configuration
The tool can utilize API keys for enhanced functionality, but all are optional:
| Service | Purpose | Get Free API Key |
|---|---|---|
| CUSIP β stock ticker (Bloomberg's free identifier mapping). Works without a key at 25 req/min; a key raises the limit to 250 req/min. | OpenFIGI Keys | |
| Reverse ticker β CUSIP lookup for Form 4 filings (free tier 250 req/day). Key required β without it the reverse lookup is skipped and unresolved tickers open a GitHub issue. | FMP Keys | |
| Access to almost any LLMs | OpenRouter Keys | |
| Access to Google Gemini models | AI Studio Keys | |
| Access to various LLMs (e.g., OpenAI gpt-oss, Meta Llama, etc...) | Groq Keys | |
| Open-weight models hosted by Ollama (e.g., Nemotron 3 Super, Gemma 4). | Ollama Keys | |
GLM models. GLM-4.7-Flash and GLM-4.5-Flash are free. |
Z.AI Keys |
π‘ Note β Ticker resolution:
Forward path (CUSIP β ticker) runs the chain in this order, no API key required for any step:
- yfinance β free, no key, covers the majority of US-listed equities.
- OpenFIGI β Bloomberg's free identifier-mapping endpoint. Works without
OPENFIGI_API_KEYat 25 req/min; with a key the limit is raised to 250 req/min.- TradingView β public symbol-search endpoint, queried by ISIN (US-listings only). When ISIN returns only non-US listings (typical for recently-renamed issuers), it retries by company name using the description TradingView itself reports β which carries the current name even if the SEC filing still lists the old one (e.g. Ekso Bionics β ChronoScale).
Reverse path (ticker β CUSIP) for Form 4 filings goes through Financial Modeling Prep. The free
FMP_API_KEYis required (250 req/day); without it, unresolved tickers open a GitHub issue and the CUSIP stays null until the next 13F cycle exposes it.π‘ Note: You don't need to use all the APIs. For the generative AI models (OpenRouter, Google AI Studio, Groq AI, Ollama Cloud, and Z.AI), you only need the API keys for the services you plan to use. The default provider is Google AI Studio, so a single free AI Studio key is enough to get started. Experimenting with different models is encouraged, as the quality of AI-generated analysis, both for identifying promising stocks and for conducting due diligence, can vary. However, top-performing stocks are typically identified consistently across all tested models. Every model in the bundled
database/models.csvruns within its provider's free tier.Using other providers' models: OpenRouter can call a provider with your key (BYOK, configured in your OpenRouter integrations); add the model to
database/models.csvwithClientset toOpenRouterand no code change is needed. OpenRouter bills 5% of the model's list price on top, from your OpenRouter credits.
π Project Structure
hedge-fund-tracker/
βββ π .github/
β βββ π ISSUE_TEMPLATE/ # Bug report + feature request forms
β βββ π scripts/
β β βββ π fetcher.py # Script for data fetching (scheduled by workflows/filings-fetch.yml)
β βββ π workflows/ # GitHub Actions for automation
β βββ βοΈ dependabot-automerge.yml # GitHub Actions: Dependabot PR auto-merge
β βββ βοΈ deploy-pages.yml # GitHub Actions: Deploy to GitHub Pages
β βββ βοΈ filings-fetch.yml # GitHub Actions: Filings fetching job
β βββ βοΈ lint.yml # GitHub Actions: Lint + type-check
β βββ βοΈ popularity-refresh.yml # GitHub Actions: Excluded-funds popularity ranking
β βββ βοΈ refresh-badges.yml # GitHub Actions: README badge refresh
β βββ βοΈ run-tests.yml # GitHub Actions: Python + frontend tests
βββ π app/ # Main application logic
β βββ π ai/ # LLM clients (OpenRouter, Google, Groq, Ollama, Z.AI) + analyst agent
β βββ π analysis/ # Portfolio, stock and performance analysis
β βββ π api/ # FastAPI routers (data, ai, sse, settings, admin, β¦)
β βββ π auth/ # Accounts, sessions and BYOK API-key storage
β βββ π backtest/ # Strategy Performance backtest engine
β βββ π db/ # SQLAlchemy models and session wiring
β βββ π frontend/ # React + Vite web UI
β β βββ π public/ # Static assets (404.html, logo + favicons)
β β βββ π scripts/ # copy-database.mjs (bundles CSVs for GH Pages)
β β βββ π src/
β β β βββ π components/ # Shared UI components (AppSidebar, GlobalSearch, ModelSelector, TerminalOutput, β¦)
β β β βββ π lib/ # config.ts (IS_GH_PAGES_MODE), dataService.ts (CSV I/O), aiClient.ts (SSE), routes.ts, menuDoors.ts
β β β βββ π pages/ # Landing, Dashboard, QuarterlyTrends, StrategyPerformance, FundPortfolio, StockBrowser, StockAnalysis, Learn, AIRanking, AIDueDiligence, FundsConfig, AISettings, DatabasePage
β β βββ π¦ package.json
β β βββ βοΈ vite.config.ts
β βββ π scraper/ # SEC EDGAR fetching and filing parsers
β βββ π security/ # Envelope encryption for stored secrets
β βββ π stocks/ # Ticker resolution + price fetching
β βββ π utils/ # Logging, console, GitHub issue alerts
β βββ π server.py # FastAPI server (serves frontend + all API endpoints)
β βββ βΆοΈ main.py # Entry point: web server (default) or CLI (--cli)
βββ π database/ # Data storage
β βββ π 2025Q1/ # Quarterly reports
β β βββ π fund_1.csv # Individual fund quarterly report
β β βββ π fund_2.csv
β β βββ π fund_n.csv
β βββ π YYYYQN/
β βββ π excluded_hedge_funds.csv # Funds deliberately not tracked (see Notable Exclusions)
β βββ π hedge_funds.csv # Curated hedge funds list -> EDIT THIS to add or remove funds to track
β βββ π models.csv # LLMs list to use for AI Financial Analyst -> EDIT THIS to add or remove AI models
β βββ π non_quarterly.csv # Stores latest 13D/G and Form 4 filings
β βββ π performance.csv # Backtested strategy equity curves
β βββ π sector_hierarchy.csv # Yahoo Finance sector β industry taxonomy
β βββ π stocks.csv # Master data for stocks (CUSIP-Ticker-Name-Sector-Industry)
β βββ βΆοΈ updater.py # Main entry point for updating the database
βββ π docs/ # Design notes and long-form documentation
βββ π scripts/ # Maintenance scripts (generate_secrets.py, regenerate_reports.py, β¦)
βββ π tests/ # Python test suite
βββ π .env.example # Template for your API keys and secrets
βββ β .gitignore # Git ignore rules
βββ βοΈ alembic.ini # Database migration configuration
βββ π³ compose.yaml # App + Postgres services
βββ π³ Dockerfile # Multi-stage image (Node build β Python runtime)
βββ βΆοΈ entrypoint.sh # Container start-up: seed data, write .env, run migrations
βββ π§Ύ LICENSE # Proprietary (code) + bundled MIT (original work)
βββ π§Ύ LICENSE-DOCS # CC BY 4.0 (Markdown documentation)
βββ π§Ύ LICENSE-DATA # CC BY-NC 4.0 (database/ data files)
βββ π οΈ Pipfile # Project dependencies
βββ π Pipfile.lock # Locked dependency versions
βββ π README.md # Project documentation (this file)
π Hedge Funds Configuration File:
database/hedge_funds.csvcontains the list of hedge funds to monitor (CIK, name, manager) and can also be edited at runtime.π LLMs Configuration File:
database/models.csvcontains the list of available LLMs for AI analysis and can also be edited at runtime.
π¨π»βπ» How This Tool Tracks Hedge Funds
This tracker leverages the following types of SEC filings to provide a comprehensive view of institutional activity.
π Quarterly 13F Filings
- Required for funds managing $100M+
- Filed within 45 days of quarter-end
- Shows portfolio snapshot on last day of quarter
π Non-Quarterly 13D/G Filings
- Required when beneficially owning more than 5% of a class of registered voting shares
- Schedule 13D is filed within 5 business days of the acquisition (amendments within 2 business days)
- Schedule 13G varies: a passive investor files within 5 business days, but a Qualified Institutional Investor files 45 days after quarter end β the same lag as a 13F
- Provides a timely view of significant investments, 13D most reliably so
βπ» Non-Quarterly SEC Form 4 Insider Filings
- Filed by insiders (executives, directors) or large shareholders (>10%) when they trade company stocks
- Must be filed within 2 business days of the transaction
- Offers real-time insight into the actions of key individuals and institutions
π’ Hedge Funds Selection
This tool tracks a curated list of what I found to be the top-performing institutional investors that file with the U.S. SEC, identified based on their performance over the last 3-5 years. This curation is the result of my own methodology designed to identify the top percentile of global investment funds. My selection methodology is detailed below.
Selection Methodology
Modern portfolio theory (MPT) offers many methods for quantifying the risk-return trade-off, but they are often ill-suited for analyzing the limited data available in public filings. Consequently, the hedge_funds.csv was therefore generated using my own custom selection algorithm designed to identify top-performing funds while managing for volatility.
Note: The selection algorithm is external to this project and was used only to produce the curated
hedge_funds.csvlist.
My approach prioritizes high cumulative returns but also analyzes the path taken to achieve them: it penalizes volatility, similar to the Sharpe Ratio, but this penalty is dynamically adjusted based on performance consistency; likewise, drawdowns are penalized, echoing the principle of the Sterling Ratio, but the penalty is intentionally dampened to avoid overly punishing funds that recover effectively from temporary downturns.
List Management
The list of hedge funds is actively managed to maintain its quality; funds that underperform may be replaced, while new top performers are periodically added.
However, despite their strong performance, several funds with portfolios predominantly focused on Healthcare and Biotech, such as Nextech Invest, Enavate Sciences, Caligan Partners, and Boxer Capital Management, have been intentionally excluded. These funds invest in highly specialized sectors where I lack the necessary expertise. Consequently, I consider them too risky for my personal investment profile, given the complexity and volatility inherent in biotech and healthcare ventures.
Notable Exclusions
The quality of the output analysis is directly tied to the quality of the input data. To enhance the accuracy of the insights and opportunities identified, many popular high-profile funds have been intentionally excluded by design (the list below is automatically managed and capped to 50 funds, but you can see the full list in excluded_hedge_funds.csv):
- Peter Thiel's Thiel Macro
- Warren Buffett's Berkshire Hathaway
- George Soros's Soros Fund Management
- Michael Burry's Scion Asset Management
- Larry Fink's BlackRock
- Bill Ackman's Pershing Square
- Ray Dalio's Bridgewater Associates
- Steven Cohen's Point72
- Paul Marshall & Ian Wace's Marshall Wace
- Carl Icahn's Icahn Enterprises
- Abigail Johnson's FMR
- Cathie Wood's ARK Invest
- Ben Horowitz's a16z
- David Tepper's Appaloosa
- Jan Koum's Newlands
- Bill Gates's Gates Foundation Trust
- Paul Tudor Jones's Tudor Investment Corporation
- Brad Gerstner's Altimeter Capital Management
- Robert Pitts's Steadfast Capital Management
- John Paulson's Paulson & Co.
- David Lane's Geode Capital Management
- Chris Hohn's The Children's Investment
- Jeremy Grantham's GMO
- Robert Granieri's Jane Street
- Tim Campbell's Baillie Gifford
- John Overdeck's Two Sigma
- Israel Englander's Millennium Management
- Mohnish Pabrai's Dalal Street
- Yosef & Eli Levy's YD More
- Li Lu's Himalaya Capital Management
- Cliff Asness's AQR Capital Management
- David Shaw's DE Shaw
- Ashish Sharma's DGS Capital Management
- Daniel Loeb's Third Point
- Dmitry Balyasny's Balyasny Asset Management
- Pierre-Yves Morlat's Qube Research & Technologies
- Seth Klarman's Baupost Group
- William Huffman's Nuveen
- Ken Fisher's Fisher Asset Management
- Joel Greenblatt's Gotham Funds
- Chase Coleman's Tiger Global
- David Booth's Dimensional Fund Advisors
- Philippe Laffont's Coatue
- Ali Dibadj's Janus Henderson Investors
- Robert Citrone's Discovery Capital Management
- Boaz Weinstein's Saba Capital
- Paul Singer's Elliott Investment
- Steve Mandel's Lone Pine Capital
- Richard Walker's Crake Asset Management
- Andreas Halvorsen's Viking Global Investors
- Mario Gabelli's GAMCO Investors
- Steven Schonfeld's Schonfeld Strategic Advisors
- Gregory Fleming's Rockefeller Capital Management
- Herbert Allen III's Allen Operations
- Barry Ritholtz's Ritholtz Wealth Management
- Lee Ainslie's Maverick Capital
- Edward Mule's Silver Point Capital
- Paul Thwaite's NatWest Group
- Tianqiao Chen's Shanda
- Bill Nygren's Harris Associates
- and many more... (see
C:\Users\dokso\Desktop\hedge-fund-tracker\database/excluded_hedge_funds.csvfor the full list)
π‘ Note: For convenience, key information for these funds, including their CIKs, is maintained in the
database/excluded_hedge_funds.csvfile.
Adding Custom Funds
Want to track additional funds? Simply edit database/hedge_funds.csv and add your preferred institutional investors. For example, to add Berkshire Hathaway, Pershing Square and ARK-Invest, you would add the following lines:
"CIK","Fund","Manager","Denomination","CIKs","URL"
"0001067983","Berkshire Hathaway","Warren Buffett","Berkshire Hathaway Inc","","https://www.berkshirehathaway.com/"
"0001336528","Pershing Square","Bill Ackman","Pershing Square Capital Management, L.P.","","https://pershingsquareholdings.com/"
"0001697748","ARK Invest","Cathie Wood","ARK Investment Management LLC","","https://www.ark-invest.com/"
π‘ Note:
hedge_funds.csvcurrently includes not only traditional hedge funds but also other institutional investors (private equity funds, large banks, VCs, pension funds, etc., that file 13F to the SEC) selected from what I consider the top 5% of performers.If you wish to track any of the Notable Exclusions hedge funds, you can copy the relevant rows from
excluded_hedge_funds.csvintohedge_funds.csv.
Columns for Custom Funds:
Denomination: This is the exact legal name used by the fund in its filings. It is essential for accurately processing non-quarterly filings (13D/G, Form 4) as the scraper uses it to identify the fund's specific transactions within complex filing documents.CIKs(optional): A comma-separated list of additional CIKs. This field is used to track filings from related entities or subsidiaries. Some investment firms have complex structures where different legal entities file separately (e.g., a management company and a holding company).Example: Jeffrey Ubben's ValueAct Holdings (CIK =
0001418814) also has filings under ValueAct Capital Management (CIK =0001418812). By adding0001418812to theCIKscolumn, the tool aggregates non-quarterly filings from both entities for a complete view."CIK","Fund","Manager","Denomination","CIKs","URL" "0001418814","ValueAct","Jeffrey Ubben","ValueAct Holdings, L.P.","0001418812","https://valueact.com/"URL(optional): Official fund website.
π§ AI Models Selection
The AI Financial Analyst ranks stocks by "Promise Score", a score a language model produces from the institutional filing data on this site: how many tracked funds hold a stock, how large those positions are, and how they changed over recent quarters. It runs in two steps β the model first proposes how much weight to give each of those inputs for the selected quarter, then scores every stock using those weights. It is a ranking of filing activity, not a forecast of returns.
The models included in database/models.csv have been selected because they have demonstrated the best performance and reliability for these specific tasks. Through experimentation, they have proven effective at interpreting the prompts and providing insightful, well-structured responses.
Adding Custom AI Models
You can easily add or change the AI models used for analysis by editing the database/models.csv file. This allows you to experiment with different Large Language Models (LLMs) from supported providers.
To add a new model, open database/models.csv and add a new row with the following columns:
- ID: The specific model identifier as required by the provider's API.
- Description: A brief, user-friendly description that will be displayed in the selection menu.
- Client: The provider of the model. Must be one of
Google,Groq,Ollama,OpenRouter, orZAI.
Here are the official model lists for each provider:
β οΈ Limitations & Considerations
It's crucial to understand the inherent limitations of tracking investment strategies solely through SEC filings:
| Limitation | Impact | Mitigation |
|---|---|---|
| π Filing Delay | Data can be 45+ days old | Focus on long-term strategies |
| π§© Incomplete Picture | Only US long positions shown | Use as part of broader analysis |
| π No Short Positions | Missing hedge information | Consider reported positions carefully |
| π Limited Scope | No non-US stocks or other assets | Supplement with additional data |
A Truly Up-to-Date View
Many tracking websites rely solely on quarterly 13F filings, which means their data can be over 45 days old and miss many significant trades. Non-quarterly filings like 13D/G and Form 4 are often ignored because they are more complex to process and merge.
This tracker helps overcome that limitation by integrating multiple filing types. When analyzing the most recent quarter, the tool automatically incorporates the latest data from 13D/G and Form 4 filings. As a result, the holdings, deltas, and portfolio percentages reflect not just the static 13F snapshot, but also any significant trades that have occurred since. This provides a more dynamic and complete picture of institutional activity.
π³ Docker Deployment
You can run the full application in Docker β no Python or Node.js installation required.
What Docker Provides
- Multi-stage build: frontend compiled in Node, served by Python β single optimized image
- Postgres service: a
postgres:18-alpinecontainer on apgdatavolume, published on loopback only; Alembic migrations run at start-up fromentrypoint.sh - Persistent data:
database/,__llmcache__/, and__reports__/are mounted as volumes - Health check:
/healthendpoint monitored by Docker - Non-root user: runs as
hedgefunduser inside the container - API keys: read from mounted
.envfile or passed as environment variables
Planned: Public Cloud Deployment
This is a roadmap item, not a supported configuration. The current release is meant for local or private-network use only; see SECURITY.md for the supported security posture.
The experimental authentication and Postgres stack in this repository is groundwork for a future hosted mode.
The container itself already carries the pieces a hosted deployment would build on: setting DOCKER_ENV=1 selects the containerized configuration, API keys are passed as environment variables, and entrypoint.sh seeds the database and generates .env from those environment variables on first start.
Before public deployment can be supported, the next step will need:
- Postgres reachable over
DATABASE_URLinstead of the bundled loopback-only container - The four secrets produced by
scripts/generate_secrets.py(MASTER_KEY,MASTER_KEY_VERSION,RESET_PASSWORD_TOKEN_SECRET,VERIFICATION_TOKEN_SECRET) supplied by the platform's secret store - HTTPS terminated in front of the application, since the app serves plain HTTP inside the container
π GitHub Pages Deployment
The frontend can be deployed as a static demo on GitHub Pages β no Python backend required. AI features and data updates are disabled in this mode, but all core analysis pages work with bundled data.
Live demo: https://{username}.github.io/hedge-fund-tracker/
What's Available in GitHub Pages Mode
| Page | Status |
|---|---|
Latest Filings (/latest) |
Fully functional |
Quarterly Trends (/quarterly) |
Fully functional |
Strategy Performance (/performance) |
Fully functional |
Fund Portfolios (/funds) |
Fully functional |
Stocks (/stocks, /stock/:ticker) |
Fully functional |
FAQ (/learn) |
Fully functional (statically pre-rendered for SEO) |
Most Promising Stocks (/ai-ranking) |
Disabled (requires local backend) |
Stock Due Diligence (/ai-diligence) |
Disabled (requires local backend) |
Funds Configuration (/funds-config) |
Hidden (Admin section not rendered) |
AI Settings (/ai-settings) |
Hidden (Admin section not rendered) |
Update Operations (/database) |
Hidden (Admin section not rendered) |
How to Deploy
- Fork the repository on GitHub
- Enable GitHub Pages: Go to Settings > Pages > Source: "GitHub Actions"
- Push to
masterβ the deploy workflow (.github/workflows/deploy-pages.yml) runs automatically
The build step (npm run build:gh-pages) bundles all CSV data into dist/database/ so the static site is fully self-contained.
Local Development
For full functionality (AI analysis, data updates, file editing), run locally:
pipenv install
pipenv run build-frontend
pipenv run app
βοΈ Automation with GitHub Actions
This repository includes a GitHub Actions workflow (.github/workflows/filings-fetch.yml) designed to keep your data effortlessly up-to-date by automatically fetching the latest SEC filings.
How It Works
- Scheduled Runs: The workflow runs automatically to check for new 13F, 13D/G, and Form 4 filings from the funds you are tracking (
hedge_funds.csv). It runs four times a day from Monday to Friday (at 01:30, 13:30, 17:30, and 21:30 UTC) and once on Saturday (at 04:00 UTC). - Safe Branching Strategy: Instead of committing directly to your main branch, the workflow pushes all new data to a dedicated branch named
automated/filings-fetch. - GitHub Pages Deploy: A separate workflow (
.github/workflows/deploy-pages.yml) automatically rebuilds and deploys the static frontend to GitHub Pages whenever frontend or database files change onmaster. - User-Controlled Merging: This approach gives you full control. You can review the changes committed by the bot and then merge them into your main branch whenever you're ready. This prevents unexpected changes and allows you to manage updates at your own pace.
- Automated Alerts: If the script encounters a non-quarterly filing where it cannot identify the fund owner based on your
hedge_funds.csvconfiguration, it will automatically open a GitHub Issue in your repository, alerting you to a potential data mismatch that needs investigation.
How to Enable It
- Fork the Repository: Create your own fork of this project on GitHub.
- Enable Actions: GitHub Actions are typically enabled by default on forked repositories. You can verify this under the Actions tab of your fork.
- Configure Secrets (optional): Workflows run with the
GITHUB_TOKENthat GitHub Actions provides automatically (it is not a personal key you create) and require no extra setup. If you want a higher OpenFIGI rate limit during ticker resolution (250 req/min vs 25), addOPENFIGI_API_KEYas a repository secret underSettings>Secrets and variables>Actions.
ποΈ Technical Stack
| ποΈ Category | π¦Ύ Technology |
|---|---|
| Core | Python 3.14+, pipenv, Docker (optional) |
| Backend | FastAPI, uvicorn |
| Persistence & Accounts | PostgreSQL, SQLAlchemy, Alembic, FastAPI Users, cryptography (envelope encryption for stored keys) |
| Frontend | React 19, Vite, TypeScript, Tailwind CSS |
| UI Components | shadcn/ui, Radix UI, Lucide, Sonner |
| Data Viz & State | Recharts, TanStack Query v5 |
| Web Scraping | curl_cffi, Beautiful Soup 4, lxml |
| Reliability | Tenacity, Python-Dotenv |
| Stocks Data | yfinance, OpenFIGI, TradingView, Financial Modeling Prep, Nasdaq API |
| Gen AI | toon-format, Google AI SDK, OpenAI SDK |
| Code Quality (Python) | Ruff (lint + format), Pyright (type-check), pre-commit |
| Code Quality (Frontend) | oxlint (React, JSX-a11y, TypeScript rules), oxfmt, TypeScript strict |
| CI/CD | GitHub Actions (lint, tests, deploy), Vitest (frontend tests), unittest (Python tests) |
π€πΌ Contributing & Support
Read CONTRIBUTING.md before opening a PR β it covers the test policy, lint policy, branch hygiene, and what makes a good PR. For deep architectural context (modules, footguns, data flow) see AGENTS.md.
π¬ Loved it? Help it grow
- π Report a bug β guided form so reproduction info isn't missed
- π Request a feature β for open-ended ideas, prefer Discussions
- π Report a vulnerability privately β never open a public issue for security
- π Fork & open a PR β small, focused PRs land faster
- π Share on X or LinkedIn
βπ» Feedback
This tool is in active development, and your input is valuable. For questions or design discussion, open a Discussion β keeping conversations public benefits future contributors.
π References
- SEC Developer Resources
- SEC: Frequently Asked Questions About Form 13F
- SEC: Guidance on Beneficial Ownership Reporting (Sections 13D/G)
- CUSIP (Committee on Uniform Security Identification Procedures)
- Modern Portfolio Theory (MPT)
ππΌ Acknowledgments
This project began as a fork of sec-web-scraper-13f by Gary Pang. The original tool provided a solid foundation for scraping 13F filings from the SEC's EDGAR database. It has since been significantly re-architected and expanded into a comprehensive analysis platform, incorporating multiple filing types, AI-driven insights, and automated data management.
π License
This repository is licensed in parts, with documentation and data carved out separately:
- Original work (Gary Pang's sec-web-scraper-13f): MIT License.
- All new code (everything added by Alessandro Colace): Copyright Β© 2025 Alessandro Colace β All Rights Reserved. Personal and educational use is permitted; redistribution and commercial use require written permission.
- Markdown documentation (
*.mdfiles): Creative Commons Attribution 4.0 International (CC BY 4.0) β reuse with attribution to Alessandro Colace (github.com/dokson/hedge-fund-tracker). Each.mdfile carries anSPDX-License-Identifier: CC-BY-4.0header. - Data (the files under
database/, also served by the site under/database/): Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0) β non-commercial reuse with attribution to Hedge Fund Tracker; commercial use requires written permission. The underlying SEC filings remain public records.
See LICENSE for the code terms, LICENSE-DOCS for the documentation terms and LICENSE-DATA for the data terms.