vibe-trading

star 12.4k

Professional finance research toolkit — backtesting (7 engines + benchmark comparison panel), factor analysis, Alpha Zoo (452 pre-built alphas across qlib158/alpha101/gtja191/academic), options pricing, 77 finance skills, 29 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 7 data sources (tushare, yfinance, okx, akshare, mootdx, ccxt, futu).

HKUDS By HKUDS schedule Updated 6/16/2026
play_arrow Run Skill in Manus View GitHub

name: vibe-trading version: 0.1.9 description: Professional finance research toolkit — backtesting (7 engines + benchmark comparison panel), factor analysis, Alpha Zoo (452 pre-built alphas across qlib158/alpha101/gtja191/academic), options pricing, 77 finance skills, 29 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 7 data sources (tushare, yfinance, okx, akshare, mootdx, ccxt, futu). dependencies: python: ">=3.11" pip: - vibe-trading-ai env:

  • name: TUSHARE_TOKEN description: "Tushare API token for China A-share data (optional — HK/US/crypto work without any key)" required: false
  • name: OPENAI_API_KEY description: "OpenAI-compatible API key — only needed for run_swarm (multi-agent teams). All other tools work without it." required: false
  • name: LANGCHAIN_MODEL_NAME description: "LLM model name for run_swarm (e.g. deepseek/deepseek-v4-pro). Only needed if using run_swarm." required: false mcp: command: vibe-trading-mcp args: []

Vibe-Trading

Professional finance research toolkit with AI-powered backtesting (7 engines), multi-agent teams, 77 specialized skills, the Alpha Zoo (452 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better.

Setup

pip install vibe-trading-ai

Package name vs commands: The PyPI package is vibe-trading-ai. Once installed, you get:

Command Purpose
vibe-trading Interactive CLI / TUI
vibe-trading serve Launch FastAPI web server
vibe-trading-mcp Start MCP server (for Claude Desktop, OpenClaw, Cursor, etc.)

Add to your agent's MCP config:

{
  "mcpServers": {
    "vibe-trading": {
      "command": "vibe-trading-mcp"
    }
  }
}

API Key Requirements

Core research MCP tools work with zero API keys for HK/US/crypto. After pip install, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (452 pre-built alphas), and all 77 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; run_swarm requires an LLM key.

Feature Key needed When
HK/US equities & crypto None Always free (yfinance + OKX)
China A-share data TUSHARE_TOKEN Only if you query A-share symbols
Multi-agent swarm (run_swarm) OPENAI_API_KEY + LANGCHAIN_MODEL_NAME Swarm spawns internal LLM workers

What You Can Do

Shadow Account — flagship loop

Feed a CSV broker export (同花顺 / 东财 / 富途 / generic), and the agent will:

  1. analyze_trade_journal — profile your behavior (holding period, win rate, disposition effect, chasing, overtrading, anchoring).
  2. extract_shadow_strategy — distill 3-5 if-then rules that describe your profitable roundtrips.
  3. run_shadow_backtest — backtest those rules across A/HK/US/crypto and compute delta-PnL vs your realized trades.
  4. render_shadow_report — produce an HTML/PDF report (8 sections + charts) with today's matching signals.
  5. scan_shadow_signals — list today's symbols that match your shadow's entry cadence (research only).

Backtesting

Create and run quantitative strategies across 7 engines (ChinaA, GlobalEquity, Crypto, ChinaFutures, GlobalFutures, Forex + options) with 7 data sources:

  • HK/US equities via yfinance (free, no API key)
  • Cryptocurrency via OKX or CCXT/100+ exchanges (free, no API key)
  • China A-shares via Tushare (token) or AKShare (free fallback)
  • Futures, forex, macro via AKShare (free, no API key)
  • HK & A-share equities via Futu (broker login required, optional)

Example workflow:

  1. Use list_skills() to discover strategy patterns
  2. Use load_skill("strategy-generate") for the strategy creation guide
  3. Use write_file() to create config.json and code/signal_engine.py
  4. Use backtest() to run and get metrics (Sharpe, return, drawdown, etc.)

Multi-Agent Swarm Teams

29 pre-built agent teams for complex research:

  • Investment Committee: bull/bear debate → risk review → PM decision
  • Global Equities Desk: A-share + HK/US + crypto → global strategist
  • Crypto Trading Desk: funding/basis + liquidation + flow → risk manager
  • Earnings Research Desk: fundamentals + revisions + options → earnings strategist
  • Macro/Rates/FX Desk: rates + FX + commodities → macro PM
  • Quant Strategy Desk: screening → factor research → backtest → risk audit
  • Risk Committee: drawdown, tail risk, regime analysis
  • And 22 more specialized teams

Use list_swarm_presets() to see all teams, then run_swarm() to execute.

Alpha Zoo (452 pre-built alphas)

One-line cross-sectional IC / IR / alive-reversed-dead categorisation across four bundled zoos:

  • qlib158 (154 alphas) — Microsoft Qlib's Alpha158 feature handler, Apache-2.0 with pinned commit SHA.
  • alpha101 (101 alphas) — Kakushadze (2015) "101 Formulaic Alphas" (arXiv:1601.00991), written from the paper appendix.
  • gtja191 (191 alphas) — Guotai Junan 2014 "191 Short-period Trading Alpha Factors" research report.
  • academic (6 factors) — Fama-French 5 + Carhart momentum (honest price-based proxies).

Each alpha ships with __alpha_meta__ (formula LaTeX + theme + universe + warmup + columns required), guarded by an AST purity gate + 300-row lookahead sentinel test. Use the vibe-trading alpha {list,show,bench,compare,export-manifest} CLI, the /alpha/* REST routes (browser at /alpha-zoo), or compose multi-factor signals via ZooSignalEngine.from_zoo(...).

Finance Skills (77)

Comprehensive knowledge base covering:

  • Technical analysis (candlestick, Elliott wave, Ichimoku, SMC, harmonic, chanlun)
  • Quantitative methods (factor research, ML strategy, pair trading, multi-factor)
  • Risk management (VaR/CVaR, stress testing, hedging)
  • Options (Black-Scholes, Greeks, multi-leg strategies, payoff diagrams)
  • HK/US equities (SEC filings, earnings revisions, ETF flows, ADR/H-share arbitrage)
  • Crypto trading desk (funding rates, liquidation heatmaps, stablecoin flows, token unlocks, DeFi yields)
  • Behavioral finance, trade journal diagnostics, shadow account
  • Macro analysis, credit research, sector rotation, and more

Use load_skill(name) to access full methodology docs with code templates.

Available MCP Tools (35)

Tool Description API Key
list_skills List all 77 finance skills None
load_skill Load full skill documentation None
start_research_goal Create an auditable research goal None
get_research_goal Read the current research goal None
add_goal_evidence Attach evidence to a research goal None
update_research_goal_status Update goal lifecycle status None
backtest Run vectorized backtest engine None*
factor_analysis IC/IR analysis + layered backtest None*
analyze_options Black-Scholes price + Greeks None
pattern_recognition Detect chart patterns (H&S, double top, etc.) None
get_market_data Fetch OHLCV data across 6 sources (auto-detect + fallback) None*
web_search Search the web via DuckDuckGo None
read_url Fetch web page as Markdown None
read_document Extract text from PDF/DOCX/XLSX/PPTX/images None
write_file Write files (config, strategy code) None
read_file Read file contents None
analyze_trade_journal Parse broker CSV → profile + behavior diagnostics None
extract_shadow_strategy Distill 3-5 if-then rules from profitable roundtrips None
run_shadow_backtest Multi-market backtest + delta-PnL attribution None*
render_shadow_report HTML/PDF shadow report (8 sections + charts) None
scan_shadow_signals Today's symbols matching the shadow's cadence None
list_swarm_presets List multi-agent team presets None
run_swarm Execute a multi-agent research team LLM key
get_swarm_status Poll swarm run status without blocking None
get_run_result Get final report and task summaries None
list_runs List recent swarm runs with metadata None
reap_stale_runs Finalize stale swarm runs None
trading_connections List selectable connector profiles None
trading_select_connection Select the default connector profile None
trading_check Check connector readiness Connector app/OAuth
trading_account Read account summary from selected connector Connector app/OAuth
trading_positions Read positions from selected connector Connector app/OAuth
trading_orders Read open orders from selected connector Connector app/OAuth
trading_quote Read a quote snapshot from selected connector Connector app/OAuth
trading_history Read historical bars from selected connector Connector app/OAuth

*A-share symbols require TUSHARE_TOKEN. HK/US/crypto are free. Trading connector rows use the selected connector profile, e.g. IBKR local TWS/Gateway or Robinhood MCP OAuth.

Quick Start

pip install vibe-trading-ai

That's it — no API keys needed for HK/US/crypto markets. Start using backtest, get_market_data, analyze_options, analyze_trade_journal, extract_shadow_strategy, web_search, the Alpha Zoo (vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025), and all 77 skills immediately.

Loading Tools from External MCP Servers

The built-in agent can load tools from your own external MCP servers in addition to its local toolset.

Note: This is the MCP client path — the opposite of the MCP plugin listed above. The plugin above makes Vibe-Trading's tools available to your agents. This section lets Vibe-Trading's own agent call tools from your servers.

Setup

Create ~/.vibe-trading/agent.json:

{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-mcp-server"],
      "toolTimeout": 30,
      "enabledTools": ["*"]
    }
  }
}

Ordinary external MCP tools appear automatically in every vibe-trading run / vibe-trading chat call. They are injected after local tools under stable names: mcp_<server>_<tool>. Live-broker MCP servers are consumed through the connector-scoped trading_* tools instead of exposing raw mcp_<broker>_* tools to the agent.

Official IBKR MCP read-only probe

Add Interactive Brokers' official MCP endpoint as a read-only external server:

{
  "mcpServers": {
    "ibkr": {
      "type": "streamableHttp",
      "url": "https://api.ibkr.com/v1/api/mcp",
      "auth": {
        "type": "oauth",
        "scopes": ["mcp.read"],
        "clientName": "Vibe-Trading",
        "cacheDir": "~/.vibe-trading/live/ibkr/oauth"
      },
      "enabledTools": ["*"]
    }
  }
}

Authorize it with vibe-trading connector authorize ibkr-live-official-mcp-readonly. The wildcard is accepted only for this mcp.read probe. Generic trading_account and trading_positions calls stay disabled until IBKR publishes stable read tool names that Vibe-Trading can map safely; mcp.write requires an explicit tool allowlist and live order-guard handling. If IBKR issues a pre-registered OAuth client, add clientId and clientSecret inside auth.

Trading connector profiles

The public trading surface is connector-first. Choose a connector profile, then paper/live is just an attribute under that connector.

pip install "vibe-trading-ai[ibkr]"
vibe-trading connector list
vibe-trading connector use ibkr-paper-local
vibe-trading connector configure ibkr-paper-local --yes
vibe-trading connector check
vibe-trading connector account
vibe-trading connector positions
vibe-trading connector orders
vibe-trading connector quote AAPL
vibe-trading connector history AAPL --duration "30 D" --bar-size "1 day"

Default ports are TWS paper 7497, IB Gateway paper 4002, TWS live-readonly 7496, and IB Gateway live-readonly 4001.

Config fields

Field Required Default Description
type stdio: no, HTTP: yes inferred only for stdio Transport type. Use sse or streamableHttp for URL-based servers.
command stdio: yes — Executable to launch
args no [] Command arguments
env no {} Extra env vars for the subprocess
url HTTP: yes — Remote SSE / streamable HTTP endpoint URL
headers no {} Extra HTTP headers for SSE / streamable HTTP servers
toolTimeout no 30 Seconds before a tool call is cancelled
enabledTools no ["*"] Allowlist of remote tool names. ["*"] enables all

For URL-based transports, type is required. The agent no longer guesses between SSE and streamable HTTP from the URL suffix.

Per-session override (API)

Security — disabled by default. mcpServers defines subprocess command/args/env and is therefore restricted to operator-level trust. API callers cannot inject MCP server definitions through POST /sessions unless the server operator explicitly opts in.

To enable session-level MCP injection, set the environment variable on the server before starting the agent:

export ALLOW_SESSION_MCP_SERVERS=1

With the opt-in active, pass mcpServers inside session.config to extend or replace the global config for that session only:

{
  "config": {
    "mcpServers": {
      "research": {
        "command": "uvx",
        "args": ["research-mcp"],
        "enabledTools": ["search"]
      }
    }
  }
}

Without ALLOW_SESSION_MCP_SERVERS=1, any mcpServers key in session.config is silently stripped before config loading. The global operator config on disk (~/.vibe-trading/agent.json) is always respected regardless of this flag.

v1 limits

  • Transport: stdio, SSE, and streamable HTTP.
  • Execution: serial only. MCP tools never enter the parallel readonly path.
  • Surfaces: tools only. Resources and prompts are not exposed.
  • Swarm: MCP tools are excluded from Swarm worker registries in v1.
  • Hot reload: not supported. Restart the process to pick up config changes.

Failure handling

Case Behavior
Missing config file falls back to empty config — no MCP servers loaded
Invalid config file logs a warning and falls back to empty config
Server fails to start that server is skipped; local tools and other servers still load
Tool call times out returns a normalized error payload instead of raising
Two server names collide after sanitization deterministic hash suffix appended; operator warning emitted

Examples

Backtest a MACD strategy on Apple:

Backtest AAPL with MACD crossover strategy (fast=12, slow=26, signal=9) for 2024

Analyze my trade journal and build a Shadow Account:

Call analyze_trade_journal on ~/Downloads/tonghuashun.csv, then extract_shadow_strategy with min_support=3, then run_shadow_backtest for the last year, then render_shadow_report.

Run an investment committee review:

Use run_swarm with investment_committee preset to evaluate NVDA. Variables: target=NVDA.US, market=US

Factor analysis on CSI 300:

Run factor_analysis on CSI 300 stocks using pe_ttm factor from 2023 to 2024

Options analysis:

Use analyze_options: spot=100, strike=105, 90 days, vol=25%, rate=3%

Install via CLI
npx skills add https://github.com/HKUDS/Vibe-Trading --skill vibe-trading
Repository Details
star Stars 12,356
call_split Forks 2,381
navigation Branch main
article Path SKILL.md
Occupations
Software Developers
More from Creator
HKUDS
HKUDS Explore all skills →