vibe-trading-ai 0.1.3

Natural-language finance research AI agent with backtesting

Vibe-Trading: Your Personal Trading Agent

One Command to Empower Your Agent with Comprehensive Trading Capabilities

Features  ·  Demo  ·  What Is It  ·  Get Started  ·  CLI  ·  API  ·  MCP  ·  Structure

「 Natural-language finance research, backtesting, and multi-agent swarm workflows across A-shares · Crypto · HK/US equities. 」

---

✨ Key Features

🔍 DeepResearch for Trading • Multi-domain analysis coverage across markets • Auto strategy and signal generation • Macro economic research and insights • Natural-language task routing via chat

🐝 Swarm Intelligence • 29 out-of-the-box trading team presets • DAG-based multi-agent orchestration • Real-time decision streaming dashboard • Custom team building through YAML

📊 Cross-Market Backtest • A-shares, HK/US equities & crypto • 7 flexible intervals from 1 min to 1 day • Daily & options portfolio engines • 15+ performance metrics & 4 optimizers

🧮 Quant Analysis Toolkit • Factor IC/IR & quantile backtest • Black-Scholes & full Greeks chain • Technical chart pattern detection • MVO, Risk Parity, BL & HRP optimizers

64 Finance Skills

Area	Examples
Technical Analysis	technical-basic, candlestick, ichimoku, harmonic, elliott-wave, smc
Quant Research	strategy-generate, multi-factor, pair-trading, factor-research, ml-strategy
Fundamentals	valuation-model, financial-statement, earnings-forecast, credit-analysis
HK/US Equities	edgar-sec-filings, earnings-revision, us-etf-flow, hk-connect-flow, adr-hshare
Crypto Desk	perp-funding-basis, liquidation-heatmap, stablecoin-flow, token-unlock-treasury, defi-yield
Macro	macro-analysis, global-macro, asset-allocation, commodity-analysis, sector-rotation
Derivatives	options-strategy, options-advanced, options-payoff, crypto-derivatives, hedging-strategy
Alt Data	social-media-intelligence, sentiment-analysis, behavioral-finance, report-generate

29 Swarm Team Presets

Preset	Workflow
investment_committee	Bull/bear debate → risk review → PM final call
global_equities_desk	A-share + HK/US + crypto researcher → global strategist
crypto_trading_desk	Funding/basis + liquidation + flow → risk manager
earnings_research_desk	Fundamental + revision + options → earnings strategist
macro_rates_fx_desk	Rates + FX + commodity → macro PM
quant_strategy_desk	Screening + factor research → backtest → risk audit
technical_analysis_panel	Classic TA + Ichimoku + harmonic + Elliott + SMC → consensus
risk_committee	Drawdown + tail risk + regime review → sign-off
global_allocation_committee	A-shares + crypto + HK/US → cross-market allocation

_{And 20 more specialist presets — run vibe-trading --swarm-presets to see all.}

🎬 Demo

https://github.com/user-attachments/assets/3d5a9653-06cd-4903-b487-dc7ce4d8d90e	https://github.com/user-attachments/assets/3f8c1301-778c-439d-8992-1ad0ac524660
☝️ Natural-language backtest & multi-agent swarm debate — Web UI + CLI

---

💡 What Is Vibe-Trading?

Vibe-Trading is a multi-agent finance research workspace. You describe what you want in plain language, and the system routes the job to the right skills, tools, data sources, and swarm preset.

• Writes and edits executable strategy code
• Routes symbols across OKX, Tushare, and yfinance automatically
• Runs portfolio backtests and options analysis
• Launches specialist research teams with DAG-based swarm execution
• Streams the full reasoning trail into web UI, CLI, and API

---

🚀 Get Started

One-line install (PyPI)

pip install vibe-trading-ai

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

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.)

vibe-trading init              # interactive .env setup
vibe-trading                   # launch CLI
vibe-trading serve --port 8899 # launch web UI
vibe-trading-mcp               # start MCP server (stdio)

Or choose a path

Path	Best for	Time
A. Docker	Try it now, zero local setup	2 min
B. Local install	Development, full CLI access	5 min
C. MCP plugin	Plug into your existing agent	3 min
D. ClawHub	One command, no cloning	1 min

Prerequisites

• An OpenAI-compatible API key (OpenRouter, DeepSeek, etc.) — the only hard requirement
• Python 3.11+ for Path B
• Docker for Path A

Tip: yfinance (HK/US equities) and OKX (crypto) are free and require no API key. You only need a Tushare token for A-share data.

Path A: Docker (zero setup)

git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
cp agent/.env.example agent/.env
# Edit agent/.env — set OPENAI_API_KEY (required)
docker compose up --build

Open http://localhost:8899. Backend + frontend in one container.

Path B: Local install

git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
python -m venv .venv

# Activate
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\Activate.ps1       # Windows PowerShell

pip install -e .
cp agent/.env.example agent/.env   # Edit — set OPENAI_API_KEY
vibe-trading                       # Launch interactive TUI

Start web UI (optional)

# Terminal 1: API server
vibe-trading serve --port 8899

# Terminal 2: Frontend dev server
cd frontend && npm install && npm run dev

Open http://localhost:5899. The frontend proxies API calls to localhost:8899.

Production mode (single server):

cd frontend && npm run build && cd ..
vibe-trading serve --port 8899     # FastAPI serves dist/ as static files

Path C: MCP plugin

See MCP Plugin section below.

Path D: ClawHub (one command)

npx clawhub@latest install vibe-trading --force

The skill + MCP config is downloaded into your agent's skills directory. See ClawHub install for details.

---

🧠 Environment Variables

Edit agent/.env:

Variable	Required	Description
OPENAI_API_KEY	Yes	OpenAI-compatible API key (OpenRouter, DeepSeek, etc.)
OPENAI_BASE_URL	Usually	API gateway URL (default: https://openrouter.ai/api/v1)
LANGCHAIN_PROVIDER	Yes	LLM provider selector (e.g. openrouter)
LANGCHAIN_MODEL_NAME	Yes	Model name (e.g. deepseek/deepseek-v3.2)
TUSHARE_TOKEN	A-shares only	Tushare Pro token for A-share data
TIMEOUT_SECONDS	No	Agent timeout, default 2400s

Free data (no key needed): HK/US equities via yfinance, crypto via OKX public API.

---

🖥 CLI Reference

vibe-trading               # interactive TUI
vibe-trading run -p "..."  # single run
vibe-trading serve         # API server

Slash commands inside TUI

Command	Description
/help	Show all commands
/skills	List all 64 finance skills
/swarm	List 29 swarm team presets
/swarm run <preset> [vars_json]	Run a swarm team with live streaming
/swarm list	Swarm run history
/swarm show <run_id>	Swarm run details
/swarm cancel <run_id>	Cancel a running swarm
/list	Recent runs
/show <run_id>	Run details + metrics
/code <run_id>	Generated strategy code
/trace <run_id>	Full execution replay
/continue <run_id> <prompt>	Continue a run with new instructions
/sessions	List chat sessions
/settings	Show runtime config
/clear	Clear screen
/quit	Exit

Single run & flags

vibe-trading run -p "Backtest BTC-USDT MACD strategy, last 30 days"
vibe-trading run -p "Analyze AAPL momentum" --json
vibe-trading run -f strategy.txt
echo "Backtest 000001.SZ RSI" | vibe-trading run

vibe-trading -p "your prompt"
vibe-trading --skills
vibe-trading --swarm-presets
vibe-trading --swarm-run investment_committee '{"topic":"BTC outlook"}'
vibe-trading --list
vibe-trading --show <run_id>
vibe-trading --code <run_id>
vibe-trading --trace <run_id>
vibe-trading --continue <run_id> "refine the strategy"
vibe-trading --upload report.pdf

---

🌐 API Server

vibe-trading serve --port 8899

Method	Endpoint	Description
GET	/runs	List runs
GET	/runs/{run_id}	Run details
POST	/sessions	Create session
POST	/sessions/{id}/messages	Send message
GET	/sessions/{id}/events	SSE event stream
POST	/upload	Upload PDF/file
GET	/swarm/presets	List swarm presets
POST	/swarm/runs	Start swarm run
GET	/swarm/runs/{id}/events	Swarm SSE stream

Interactive docs: http://localhost:8899/docs

---

🔌 MCP Plugin

Vibe-Trading exposes 16 MCP tools for any MCP-compatible client. Runs as a stdio subprocess — no server setup needed. 15 of 16 tools work with zero API keys (HK/US/crypto). Only run_swarm needs an LLM key.

Claude Desktop

Add to claude_desktop_config.json:

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

OpenClaw

Add to ~/.openclaw/config.yaml:

skills:
  - name: vibe-trading
    command: vibe-trading-mcp

Cursor / Windsurf / other MCP clients

vibe-trading-mcp                  # stdio (default)
vibe-trading-mcp --transport sse  # SSE for web clients

MCP tools exposed (16): list_skills, load_skill, backtest, factor_analysis, analyze_options, pattern_recognition, get_market_data, read_url, read_document, read_file, write_file, list_swarm_presets, run_swarm, get_swarm_status, get_run_result, list_runs.

Install from ClawHub (one command)

npx clawhub@latest install vibe-trading --force

--force is required because the skill references external APIs, which triggers VirusTotal's automated scan. The code is fully open-source and safe to inspect.

This downloads the skill + MCP config into your agent's skills directory. No cloning needed.

Browse on ClawHub: clawhub.ai/skills/vibe-trading

OpenSpace — self-evolving skills

All 64 finance skills are published on open-space.cloud and evolve autonomously through OpenSpace's self-evolution engine.

To use with OpenSpace, add both MCP servers to your agent config:

{
  "mcpServers": {
    "openspace": {
      "command": "openspace-mcp",
      "toolTimeout": 600,
      "env": {
        "OPENSPACE_HOST_SKILL_DIRS": "/path/to/vibe-trading/agent/src/skills",
        "OPENSPACE_WORKSPACE": "/path/to/OpenSpace"
      }
    },
    "vibe-trading": {
      "command": "vibe-trading-mcp"
    }
  }
}

OpenSpace will auto-discover all 64 skills, enabling auto-fix, auto-improve, and community sharing. Search for Vibe-Trading skills via search_skills("finance backtest") in any OpenSpace-connected agent.

---

📁 Project Structure

Click to expand

Vibe-Trading/
├── agent/                          # Backend (Python)
│   ├── cli.py                      # CLI entrypoint — interactive TUI + subcommands
│   ├── api_server.py               # FastAPI server — runs, sessions, upload, swarm, SSE
│   ├── mcp_server.py               # MCP server — 16 tools for OpenClaw / Claude Desktop
│   │
│   ├── src/
│   │   ├── agent/                  # ReAct agent core
│   │   │   ├── loop.py             #   main reasoning loop
│   │   │   ├── skills.py           #   skill loader (64 SKILL.md files)
│   │   │   ├── tools.py            #   tool orchestration
│   │   │   ├── context.py          #   system prompt builder
│   │   │   ├── memory.py           #   run memory / artifact store
│   │   │   └── trace.py            #   execution trace writer
│   │   │
│   │   ├── tools/                  # 20 agent tools
│   │   │   ├── backtest_tool.py    #   run backtests
│   │   │   ├── factor_analysis_tool.py
│   │   │   ├── options_pricing_tool.py
│   │   │   ├── pattern_tool.py     #   chart pattern detection
│   │   │   ├── doc_reader_tool.py  #   PDF reader (OCR fallback)
│   │   │   ├── web_reader_tool.py  #   web page reader (Jina)
│   │   │   ├── swarm_tool.py       #   launch swarm teams
│   │   │   └── ...                 #   file I/O, bash, tasks, etc.
│   │   │
│   │   ├── skills/                 # 64 finance skill definitions (SKILL.md each)
│   │   ├── swarm/                  # Swarm DAG execution engine
│   │   ├── session/                # Multi-turn chat session management
│   │   └── providers/              # LLM provider abstraction
│   │
│   ├── backtest/                   # Backtest engines
│   │   ├── engines/                #   daily_portfolio + options_portfolio
│   │   ├── loaders/                #   tushare, okx, yfinance
│   │   └── optimizers/             #   MVO, equal vol, max div, risk parity
│   │
│   └── config/swarm/               # 29 swarm preset YAML definitions
│
├── frontend/                       # Web UI (React 19 + Vite + TypeScript)
│   └── src/
│       ├── pages/                  #   Home, Agent, RunDetail, Compare
│       ├── components/             #   chat, charts, layout
│       └── stores/                 #   Zustand state management
│
├── Dockerfile                      # Multi-stage build
├── docker-compose.yml              # One-command deploy
├── pyproject.toml                  # Package config + CLI entrypoint
└── LICENSE                         # MIT

---

🏛 Ecosystem

Vibe-Trading is part of the HKUDS agent ecosystem:

ClawTeam Agent Swarm Intelligence

NanoBot Ultra-Lightweight Personal AI Assistant

CLI-Anything Making All Software Agent-Native

OpenSpace Self-Evolving AI Agent Skills

---

Disclaimer

Vibe-Trading is for research, simulation, and backtesting only. It is not investment advice and it does not execute live trades. Past performance does not guarantee future results.

License

MIT License — see LICENSE

---

Thanks for visiting Vibe-Trading ✨