██╗ ██╗███████╗██╗███████╗███████╗███╗ ██╗██████╗ ███████╗██████╗ ██████╗ ██║ ██║██╔════╝██║██╔════╝██╔════╝████╗ ██║██╔══██╗██╔════╝██╔══██╗██╔════╝ ███████║█████╗ ██║███████╗█████╗ ██╔██╗ ██║██████╔╝█████╗ ██████╔╝██║ ███╗ ██╔══██║██╔══╝ ██║╚════██║██╔══╝ ██║╚██╗██║██╔══██╗██╔══╝ ██╔══██╗██║ ██║ ██║ ██║███████╗██║███████║███████╗██║ ╚████║██████╔╝███████╗██║ ██║╚██████╔╝ ╚═╝ ╚═╝╚══════╝╚═╝╚══════╝╚══════╝╚═╝ ╚═══╝╚═════╝ ╚══════╝╚═╝ ╚═╝ ╚═════╝
An autonomous financial research agent with the strategic intelligence of the world's top hedge funds.
"I am the danger."
Heisenberg is a terminal-based autonomous financial research agent that reasons through complex market questions like a professional analyst — and then cross-checks its conclusions through the lens of the world's most successful hedge fund strategies.
Ask it "Should I be concerned about Apple's margin compression?" and Heisenberg doesn't just pull numbers. It plans a research sequence, fetches live fundamentals and SEC filings, applies the AQR quantitative factor framework, stress-tests the thesis against Bridgewater's macro regime analysis, checks if Elliott would view this as an activist opportunity — and delivers a structured, data-backed answer that rivals what a junior analyst at a top fund would produce.
It runs entirely in your terminal. No browser tab. No dashboard subscription. Just you, a query, and an agent that knows how to think.
Most financial tools give you data. Heisenberg gives you analysis — structured around how the best investors in the world actually think.
| What others give you | What Heisenberg gives you |
|---|---|
| Raw price and fundamentals data | Data interpreted through 8 hedge fund strategy lenses |
| Static reports | Live, autonomous research that adapts mid-task |
| Single-stock answers | Multi-ticker comparison with ASCII charts in the terminal |
| Manual monitoring | Scheduled alerts when thresholds are crossed |
| One model of the world | Macro + Quant + Activist + Arb cross-checked simultaneously |
This is what makes Heisenberg different. Every analysis is enriched by a strategy library built from studying the philosophies of the 8 largest and most successful hedge funds:
| Fund | AUM | Strategy Lens in Heisenberg |
|---|---|---|
| Citadel | $445B | Global Macro + Commodities + Multi-Strategy |
| AQR Capital | $160B | Quantitative Factor (value, momentum, quality, low-vol) |
| D.E. Shaw | $154B | Statistical Arbitrage + ML signal framework |
| Bridgewater | $136B | All-Weather / Risk-Parity + macro regime analysis |
| Two Sigma | $110B | Long/Short Equity + alternative data signals |
| Renaissance Technologies | $91B | Statistical pattern + PEAD + vol surface analysis |
| Elliott Management | $76B | Activist value + sum-of-parts + capital structure |
| Farallon Capital | $48B | Merger arbitrage + risk arbitrage |
When you ask Heisenberg a question, a Router Agent identifies which strategy lenses are most relevant and spins up specialist sub-agents — a Quant Agent, a Macro Agent, an Activist Agent — that each bring their framework to the same data before the Answer Agent synthesizes a final view.
Autonomous multi-step research Heisenberg decomposes your question into an ordered task plan, executes each step using the right tool, validates completeness, and retries gaps — all without you intervening.
Hedge fund strategy lenses Eight real-world investment frameworks are encoded into the agent's reasoning: All-Weather, Global Macro, Quantitative Factor, Statistical Arb, Long/Short Equity, Activist Value, Merger Arb, and Distressed Credit.
Live financial data Income statements, balance sheets, cash flow statements, SEC filings (10-K, 10-Q, 8-K), insider transactions, and real-time price data via Financial Datasets API.
Web intelligence Pulls earnings call transcripts, analyst commentary, and news via Exa/Tavily search — then reads full pages with a Playwright-backed browser tool when needed.
Multi-ticker comparison with ASCII charts Compare AAPL vs MSFT vs GOOGL on any metric. Results render as formatted tables and ASCII line charts directly in the terminal — no browser required.
Alert daemon
Define threshold rules in watchlist.json — e.g. "alert me when NVDA P/E > 40" or "flag TSLA if revenue growth YoY drops below 10%" — and run the background daemon. Heisenberg polls on a cron schedule and fires a terminal alert when conditions are met, logging everything to JSONL for audit.
Full scratchpad logging
Every tool call, argument set, raw result, and LLM summary is written to .heisenberg/scratchpad/ as JSONL — fully inspectable, great for debugging or reviewing past research.
Multi-provider LLM support OpenAI (default), Anthropic Claude, Google Gemini, xAI Grok, OpenRouter, and local Ollama. Switch by changing one env variable.
Safety rails
Built-in loop detection, configurable max_steps per task and globally, and a timeout guard prevent runaway or infinite execution.
User query / alert trigger
│
▼
┌─────────────┐
│ Router agent│ ← picks strategy lens(es) for this query
└──────┬──────┘
┌─────┼──────┐
▼ ▼ ▼
Quant Macro Activist ← specialist sub-agents
agent agent agent
└─────┬──────┘
▼
┌─────────────┐
│ Action agent│ ← executes tools with strategy context
└──────┬──────┘
┌─────┼──────────────┬──────────┐
▼ ▼ ▼ ▼
Financials SEC filings Web search Alert engine
Chart renderer
│
▼
┌──────────────┐
│ Validation │ ── retry loop ──▶ Action agent
│ agent │
└──────┬───────┘
▼
┌─────────────┐
│ Answer agent│ ← synthesizes with hedge-fund framing
└──────┬──────┘
┌─────┼──────────────┐
▼ ▼ ▼
Terminal ASCII Alert
output charts fired
- Bun v1.0+
- OpenAI API key — get one here
- Financial Datasets API key — get one here (AAPL, NVDA, MSFT are free)
- Exa API key — get one here (optional, for web search)
# 1. Clone the repository
git clone https://github.com/usergotnewexp/Heisenberg-.git
cd Heisenberg-
# 2. Install dependencies
bun install
# 3. Set up environment
cp env.example .env
# Edit .env and add your API keys
# 4. Run
bun startInstall Bun if you don't have it:
# macOS / Linux
curl -fsSL https://bun.com/install | bash
# Windows
powershell -c "irm bun.sh/install.ps1|iex"bun startHeisenberg launches an interactive terminal session. Type any financial research question:
> Analyze Apple's margin trajectory and what an activist would demand
> Compare NVDA vs AMD vs INTC on quantitative factor scores
> Is the current macro regime favorable for long-duration bonds?
> Run a merger arb analysis on the latest announced acquisition in tech
> What does Bridgewater's All-Weather model say about gold right now?
bun start -- --compare AAPL,MSFT,GOOGL --metric "operating_margin"Define your watchlist in .heisenberg/watchlist.json:
[
{
"ticker": "NVDA",
"metric": "pe_ratio",
"condition": "greater_than",
"threshold": 40,
"message": "NVDA P/E has crossed 40x — elevated vs historical"
},
{
"ticker": "TSLA",
"metric": "revenue_growth_yoy",
"condition": "less_than",
"threshold": 0.10,
"message": "TSLA revenue growth has fallen below 10% YoY"
}
]Then run the daemon:
bun run alertThe daemon polls on your configured interval and fires a terminal notification + appends to .heisenberg/alerts.jsonl when a condition is triggered.
bun devAll configuration lives in .env. Copy env.example to get started.
| Variable | Required | Description |
|---|---|---|
OPENAI_API_KEY |
Yes (default) | OpenAI API key |
ANTHROPIC_API_KEY |
No | Use Claude models instead |
FINANCIAL_DATASETS_API_KEY |
Yes | Market data (AAPL/NVDA/MSFT free) |
EXASEARCH_API_KEY |
No | Web search via Exa |
TAVILY_API_KEY |
No | Web search fallback |
LLM_PROVIDER |
No | openai (default) | anthropic | ollama |
OLLAMA_BASE_URL |
No | Local Ollama endpoint |
ALERT_POLL_INTERVAL |
No | Alert daemon poll frequency in seconds (default: 60) |
You can explicitly invoke a strategy lens in your query:
| Invocation | Strategy Applied |
|---|---|
| "Use the All-Weather framework..." | Bridgewater risk-parity + macro regime |
| "Apply a quant factor screen to..." | AQR/D.E. Shaw factor scoring |
| "What would an activist say about..." | Elliott sum-of-parts + capital structure |
| "Run merger arb analysis on..." | Farallon spread + deal completion probability |
| "Stat arb: is there a pair trade..." | Renaissance z-score + spread mean reversion |
| "Distressed credit analysis of..." | Capital structure mapping + recovery scenarios |
| "Global macro view on..." | Citadel rate differential + policy divergence |
| "Long/short thesis for..." | Two Sigma fundamental + revision momentum |
Or let the Router Agent pick the right lens automatically based on your question.
Every research session creates a JSONL log in .heisenberg/scratchpad/:
.heisenberg/
├── scratchpad/
│ ├── 2025-01-30-111400_9a8f10723f79.jsonl
│ └── 2025-01-30-143022_a1b2c3d4e5f6.jsonl
├── alerts.jsonl
└── watchlist.json
Each line is one of:
init— the original query and selected strategy lenstool_result— tool name, args, raw result, LLM summarythinking— agent reasoning stepsalert— triggered alert with timestamp and metric value
Individual investors who want institutional-quality analysis without paying for institutional research.
Finance students studying how top funds think — this is a living, interactive implementation of their frameworks.
Quant developers who want a hackable autonomous agent as a base to extend with their own signals, data sources, or strategy logic.
Portfolio builders looking for a standout project that demonstrates: autonomous agent design, LLM tool use, financial domain knowledge, and systems thinking.
- Portfolio-level analysis (input your holdings, get risk attribution)
- Earnings call transcript summarization with sentiment scoring
- Backtesting module — test a strategy lens against historical data
- WhatsApp / Telegram gateway for alert delivery
- Vector memory — remember past research sessions per ticker
- MCP server integration for use in Claude Desktop
Pull requests are welcome. Please keep them small and focused — one feature or fix per PR.
# Fork, then clone your fork
git clone https://github.com/YOUR_USERNAME/Heisenberg-.git
# Create a feature branch
git checkout -b feature/your-feature-name
# Make your changes, then push
git push origin feature/your-feature-name
# Open a Pull RequestHeisenberg is a research and educational tool. Nothing it produces constitutes financial advice. All analysis is generated by AI models and should be independently verified before making any investment decision. Past hedge fund strategies described are for educational purposes only.
MIT License — © 2025 Your Name
Built with purpose. Named with intent.
"Say my name."