OpenCandle is an open source financial investigator built with TypeScript and Pi. Pi is the bundled local agent runtime that provides the terminal UI, model auth, session storage, slash commands, and extension hooks. OpenCandle adds finance research on top: it understands what kind of financial question you asked, gathers market, macro, options, fundamentals, filings, sentiment, and portfolio evidence from real sources, then turns that evidence into a risk-aware answer.

This repository is useful in three ways:

Run opencandle as an interactive CLI for market research
Open the local GUI for chat, tool discovery, provider status, and session history
Extend OpenCandle with new tools, providers, or Pi-compatible add-on packages

OpenCandle terminal demo

Why OpenCandle?

Financial research gets messy when evidence is scattered across quote pages, filings, macro dashboards, sentiment feeds, and ad hoc spreadsheets. OpenCandle gives the agent explicit tools, provider boundaries, and local state so research stays inspectable: gather the data first, show the gaps, then synthesize without pretending uncertainty disappeared.

OpenCandle is strongest when the answer depends on live or inspectable financial evidence: quotes, histories, options chains, filings, macro series, sentiment, local portfolio state, and source-gap disclosure. It can also answer educational questions without forcing unnecessary data lookups. OpenCandle's job is to make financial research auditable and useful without pretending uncertainty disappeared.

What You Can Use It For

Quote and history lookups for stocks and crypto
Options chains with locally computed Greeks
Company fundamentals, earnings, and SEC filings
FRED macro series and the alternative.me crypto Fear & Greed index
Reddit-based sentiment and discussion lookups
Portfolio tracking, watchlists, correlation, and risk analysis
Multi-step workflows such as /analyze NVDA
Clarifying follow-ups when a ticker, goal, horizon, or risk profile is ambiguous
Source-gap and stale-data warnings when a provider is missing, delayed, or unavailable

OpenCandle is designed to fetch and format data. The model handles synthesis. Tool code should not invent financial conclusions or hardcode market numbers.

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

Install And Run

Requires Node.js ^20.19.0, ^22.12.0, or >=24.0.0 <27.

CLI

npm install -g opencandle
opencandle

# or without installing globally
npx opencandle@latest

From Source

npm install
cp .env.example .env
npm start

On Windows Command Prompt, use copy .env.example .env instead of cp .env.example .env.

On first run, OpenCandle walks you through model setup. You can rerun that flow later with /setup.

For a step-by-step happy path, see docs/first-run.md.

Configuration

Model access comes from Pi. Market data providers are optional and additive. A .env file in the current working directory is loaded at startup, and env values override values from ~/.opencandle/config.json. If the same key is both exported in your shell and present in .env, the .env value wins.

Key	Required	Used For
`GEMINI_API_KEY`	No	Google models through Pi
`OPENAI_API_KEY`	No	OpenAI models through Pi
`ANTHROPIC_API_KEY`	No	Anthropic models through Pi
`ALPHA_VANTAGE_API_KEY`	No	Fundamentals, earnings, financial statements
`FRED_API_KEY`	No	Macro series such as rates, CPI, GDP, unemployment
`BRAVE_API_KEY`	No	Brave web search fallback
`EXA_API_KEY`	No	Exa web search
`FINNHUB_API_KEY`	No	Finnhub company news for sentiment summaries
`OPENCANDLE_HOME`	No	Override OpenCandle state directory
`OPENCANDLE_ROUTER_MODE`	No	Advanced request-understanding mode; keep the default unless debugging
`OPENCANDLE_TOOL_SCOPE_MODE`	No	`observe` by default; set `enforce` to apply route-selected active tools
`OPENCANDLE_DEBATE`	No	Set `false` or `0` to disable bull/bear debate
`OPENCANDLE_GUI_HOST`	No	GUI bind host, default `127.0.0.1`
`OPENCANDLE_GUI_PORT`	No	GUI port, default `14567`

Yahoo Finance, CoinGecko, Reddit, SEC EDGAR, DuckDuckGo search, and the alternative.me crypto Fear & Greed index do not require keys.

OpenCandle stores its own user state in ~/.opencandle/ by default. Pi configuration stays in .pi/ and ~/.pi/agent/. The CLI should not depend on repo-local .pi/extensions/.

Provider keys can also be stored in ~/.opencandle/config.json:

{
  "providers": {
    "alphaVantage": {
      "apiKey": "..."
    },
    "fred": {
      "apiKey": "..."
    },
    "brave": {
      "apiKey": "..."
    },
    "exa": {
      "apiKey": "..."
    },
    "finnhub": {
      "apiKey": "..."
    }
  }
}

Environment variables override values from ~/.opencandle/config.json. Set OPENCANDLE_HOME if you want OpenCandle state somewhere other than ~/.opencandle/.

See docs/configuration.md for the full env var, file config, state file, and GUI runtime reference.

Basic Usage

OpenCandle runs inside Pi's interactive terminal UI. The local GUI can be started with opencandle gui from an installed package or npm run gui from a checkout.

See docs/tui.md for terminal usage, sessions, and slash-command behavior.

Useful commands:

/setup
/login
/model
/connect
/analyze AAPL

Example prompts:

What is AAPL trading at?
Get the options chain for TSLA expiring next month
Show me MSFT 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

Local GUI

The GUI is a local browser workbench for chat, session history, tool discovery, provider setup, and richer financial result cards.

opencandle gui
# or from a checkout
npm run gui

Then open http://127.0.0.1:14567.

OpenCandle GUI

From the GUI you can ask normal chat questions, launch workflows from the catalog, run one tool directly, answer clarification cards, inspect tool output, connect provider keys, and reopen prior sessions. Workflow catalog entries become structured chat prompts, so the result still appears in the same transcript with tool cards and source warnings.

The GUI reports whether it is the session writer or a read-only follower at /health. See docs/gui-quickstart.md.

Data Sources And Tool Coverage

Area	Examples	Source
Market data	quotes, history, ticker search, crypto price/history	Yahoo Finance, Alpha Vantage fallback when configured, CoinGecko
Options	chains, open interest, IV, Greeks	Yahoo Finance plus local calculations
Fundamentals	overview, financials, earnings, DCF, company comparison	Alpha Vantage
Macro	economic series, crypto Fear & Greed	FRED, alternative.me
Technical	indicators, strategy backtests	Local calculations over market history
Sentiment	Reddit, Twitter/X, Finnhub news, and web sentiment with cross-source pipeline	Reddit JSON API, Twitter/X local browser session, Finnhub, Exa, Brave, DuckDuckGo
Filings	SEC filing search	SEC EDGAR
Portfolio	watchlist, prediction tracking, correlation, risk	Local state plus market data

Engineering Notes

Project Shape

src/
├── providers/    API clients
├── tools/        Tool implementations by domain
├── infra/        Cache, rate limiter, HTTP, browser, paths
├── routing/      Request understanding, entity extraction, and slot resolution
├── workflows/    Multi-step workflow builders
├── memory/       SQLite-backed state and retrieval
├── analysts/     Multi-analyst orchestration
├── pi/           Pi integration and session wiring
└── index.ts      Public exports

Development Commands

npm start
npm run gui
npm run docs:site:build
npm test
npm run test:watch
npm run test:e2e
npm run test:e2e:cli
npm run test:e2e:providers
npm run test:evals
npm run test:evals:product
npm run test:evals:competitive

npm test is the required baseline check after changes.

The e2e, provider, and eval commands can hit live APIs, live model providers, or local agent CLIs. Run them intentionally; see docs/testing-and-evals.md.

Repository Rules That Matter

TDD is mandatory for behavior changes
Unit tests mock globalThis.fetch and use JSON fixtures
Use cache and rateLimiter for external calls
Tools fetch and format data; analysts and prompts synthesize
Keep typing strict and use .js extensions on relative imports

Public Package Exports

Besides the CLI, the package exposes pieces for engineers building on top of OpenCandle:

opencandle
opencandle/tool-kit
opencandle/infra
opencandle/types
opencandle/providers
opencandle/tools
opencandle/workflows

If you want to add a new tool or publish an add-on package, start with docs/build-a-tool.md.

Testing The Agent

For end-to-end agent driving with file-based IPC:

npx tsx tests/harness/cli.ts run --prompt "What is AAPL trading at?" --ipc /tmp/opencandle-ipc &
npx tsx tests/harness/cli.ts wait --ipc /tmp/opencandle-ipc
npx tsx tests/harness/cli.ts trace --ipc /tmp/opencandle-ipc

The harness writes status and trace files into the IPC directory. See tests/harness/README.md for the full flow.

Project Docs

Website

The static website lives in website/. It builds a product landing page plus the public Markdown docs into website/dist/.

npm run docs:site:build
npm run docs:site:serve

GitHub Pages can publish the generated artifact through the included Pages workflow.

Keywords

FAQs

What is opencandle?

Is opencandle well maintained?

Package last updated on 26 May 2026

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install