Skip to content
OpenFin

OpenFin

Structured data commands for portfolio, market, and investment decision workflows — designed to be composed by AI agents or used directly by humans.

Design Philosophy

The CLI is a structured data tool: it fetches, computes, stores, and renders. It does not call LLM APIs. All interpretation — evidence extraction, thesis evaluation, narrative generation — happens in the calling agent session.

  • Any agent works. Claude Code, a custom Agent SDK app, or a human can drive the same workflow.
  • Deterministic core. Composite scores, action thresholds, and risk computations are rule-based. Agent judgment enters only through score assignment, evidence recording, and narrative annotation.
  • Natural fallback. Without an agent, the CLI still produces data-complete reports with empty scores and template narratives.

What It Does

Every week, run one workflow that gathers portfolio, market, macro, thesis, and filing data, then outputs:

  1. A recommendation per position/thesis: BUY_MORE, HOLD, TRIM, EXIT.
  2. Thesis condition checks — quantitative pass/fail against live quotes.
  3. Evidence records linking decisions to SEC filings, news, and market data.
  4. Portfolio-level risk analysis (concentration, sector exposure, volatility).
  5. A prioritized action list with evidence and confidence.

Installation

Prerequisites

  • Python 3.12+
  • uv package manager

Install

git clone <repo-url> && cd openfin
uv sync

Or with dev dependencies (for testing and docs):

make install-dev

Verify:

uv run openfin --help

You should see the top-level command groups: account, portfolio, order, quote, market, watchlist, earnings, news, search, thesis, sec, review, db, and service.

Set Up

Run the interactive setup wizard:

uv run openfin init

This will:

  1. Create ~/.openfin/ with seed data (theses, scoring rubrics)
  2. Walk you through entering API credentials (saved to ~/.openfin/credentials.toml)
  3. Validate connections to SnapTrade and FRED

Override the data directory with OPENFIN_HOME=/path/to/dir.

Required Keys

Key Service How to get it
[snaptrade] client_id SnapTrade (brokerage) Sign up at snaptrade.com
[snaptrade] consumer_key SnapTrade Same signup — app API secret
[snaptrade] user_id SnapTrade Generated via registerUser API call
[snaptrade] user_secret SnapTrade Returned with user ID
[finnhub] api_key Finnhub (market data) Free at finnhub.io/register
[fred] api_key FRED (macro indicators) Free at fred.stlouisfed.org

Optional Keys

Key Service How to get it
[telegram] bot_token Telegram event source Create bot via @BotFather
[brave] api_key Brave Search (web research) Free at brave.com/search/api
[sec] user_agent SEC EDGAR (filings) Set to "Your Name your@email.com" per SEC fair access policy

Re-run openfin init any time to fill in keys you skipped, or edit ~/.openfin/credentials.toml directly.

Data Sources

Source Provider What it provides API key
Market data Finnhub Quotes, index/sector performance, earnings calendar, news headlines FINNHUB_API_KEY
Brokerage SnapTrade Account balances, positions, order history SNAPTRADE_*
Macro FRED Fed funds rate, treasury yields, CPI, unemployment, jobless claims FRED_API_KEY
Web search Brave Search Recent news, analyst coverage, research per symbol BRAVE_API_KEY
SEC filings EDGAR 10-K, 10-Q, 8-K annual and quarterly reports SEC_USER_AGENT

Agent Workflow

The weekly review is a multi-step agent workflow:

1. openfin review weekly                        # CLI gathers data, persists overview + per-symbol scoring packets
2. Agent reads {DATE}_symbols/{SYMBOL}.md   # Agent reads each symbol's context on demand
3. openfin review score SYMBOL ...              # Agent records rubric scores
4. openfin review evidence SYMBOL ...           # Agent records structured evidence
5. openfin review annotate --run-id ID ...      # Agent writes narrative sections
6. openfin review finalize --run-id ID          # CLI computes composites, produces report

Steps 2-5 are where the agent (or human) applies judgment. The CLI handles everything else deterministically.

Autonomous mode: The event service can run this workflow end-to-end via a headless Claude Code session triggered by cron or Telegram command. See Event Service for details.

Documentation