OpenCandle

OpenCandle is an open source financial investigator that uses real-time provider data to try to accurately answer financial questions. Use it at web.opencandle.app with nothing to install, or install locally for the local GUI and the terminal (TUI).

# Web app: open https://web.opencandle.app (nothing to install)
npx opencandle       # terminal
npx opencandle gui   # local browser UI at http://127.0.0.1:14567

Docs | Getting started | GUI quickstart | Data sources | Build a tool

See It Work

https://github.com/user-attachments/assets/334956b1-18b4-4d6f-92b5-3f739824cd29

Why OpenCandle

Generic LLMs answer too early. OpenCandle is built around the opposite loop: understand the question, gather market evidence, disclose missing or stale data, then synthesize.

Use it when a question needs inspectable evidence:

• What is this stock or crypto trading at right now?
• How do two companies compare across price action, fundamentals, filings, and sentiment?
• What does the options chain imply, and where are the Greeks?
• How exposed is my local portfolio or watchlist?
• What macro series, filings, or sentiment sources support the answer?

OpenCandle is read-only research software. It does not place trades, route orders, or provide financial advice.

Features

• Web app: the same agent running in your browser at web.opencandle.app, with nothing to install and your data kept in the browser.
• Terminal agent: keyboard-driven research in the bundled Pi TUI, with sessions, slash commands, and saved transcripts.
• Local browser GUI: chat with result cards and interactive charts, a market dashboard, per-ticker symbol pages, watchlists and portfolios with live sparklines.
• Evidence-first answers: tools fetch and format data; the model synthesizes only after evidence is gathered.
• Finance routing: quotes, comparisons, portfolio reviews, options, filings, macro, sentiment, and education each get a purpose-built research path.
• Provider transparency: missing keys, degraded sources, and stale data are disclosed instead of hidden.
• Local state: watchlists, portfolios, and alerts stay on your device, under ~/.opencandle/ for local installs and in browser storage for the web app.
• Extensible: typed TypeScript tool APIs for building and publishing add-on tools.

Quick Start

Local installs require Node.js 22.19+ or 24–26. macOS and Linux are fully supported; Windows is best-effort (WSL recommended). The web app at web.opencandle.app needs no install.

npx opencandle

On first run, OpenCandle walks you through model setup: use Pi sign-in when offered, or provide a model API key (in the GUI, use the API-key setup panel). Data-provider keys are separate and optional. For the five-minute path from install to a first answer, see Getting Started.

Check your setup anytime with npx opencandle doctor (or Settings, then Diagnostics, in the GUI).

Example Prompts

What is AAPL trading at?
Compare MSFT and GOOGL using price, fundamentals, and sentiment
Show me TSLA puts with Greeks
Get the fed funds rate from FRED
Add 100 shares of NVDA at 120 to my portfolio, then show my portfolio
Run risk analysis on SPY
/analyze NVDA   # deep research: multi-analyst debate, takes a few minutes

Data Sources

Quotes, history, screeners, options chains, crypto, SEC filings, macro series, event probabilities, and cross-source sentiment, from Yahoo Finance, TradingView, CoinGecko, SEC EDGAR, FRED, Polymarket, alternative.me, and more. Most sources work without API keys; Alpha Vantage, FRED, Brave, Exa, Finnhub, and London Strategic Edge unlock deeper coverage when configured, and Reddit/Twitter sentiment uses rdt-cli / twitter-cli with your normal browser sessions. Full coverage tables in Data Sources.

Configuration

Model access is configured through Pi on first run (GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, or Pi sign-in). Data-provider keys are optional and can be set in the environment, through /connect, through Settings, then Data providers, in the GUI, or in ~/.opencandle/config.json; environment variables override the config file. See Configuration for the full key reference and advanced switches.

How It Fits Together

User prompt
  -> routing and slot resolution
  -> tools and workflows gather provider-backed evidence
  -> provider gaps, stale data, and warnings are preserved
  -> model synthesizes a risk-aware answer
  -> terminal or GUI session records the trace

To add a first-party tool or publish an add-on package, start with Build a Tool.

Development

git clone https://github.com/Kahtaf/OpenCandle.git
cd OpenCandle
npm install
cp .env.example .env   # optional provider keys (copy .env.example .env on Windows CMD)
npm start              # terminal agent
npm run gui            # browser GUI
npm test               # unit tests

Contributor conventions live in AGENTS.md and CONTRIBUTING.md. The e2e, provider, and eval suites can hit live APIs and model providers; run them intentionally, and see Testing and Evals.

Documentation

• Getting Started
• Ways to Run OpenCandle
• Web App Quickstart
• How the Web App Works
• TUI Quickstart
• GUI Quickstart
• Investigation Recipes
• Data Sources
• Configuration
• System Architecture
• Testing and Evals
• Why OpenCandle

Community and Contributing

Questions and bug reports are welcome in GitHub Issues; redact API keys, account identifiers, holdings, and local state from public issues. Before opening large changes or reporting sensitive issues, see Contributing, Security, and the Code of Conduct.

License

MIT. See LICENSE.