vibe-trading-ai 0.1.5

Natural-language finance research AI agent with backtesting

English | 中文 | 日本語 | 한국어 | العربية

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  ·  Roadmap  ·  Contributing  ·  Contributors

---

📰 News

• 2026-04-19 📦 v0.1.5: Published to PyPI & ClawHub. python-multipart CVE floor bump, 5 new MCP tools wired (analyze_trade_journal + 4 shadow-account tools), pattern_recognition → pattern registry fix, Docker dep parity, SKILL manifest synced (22 MCP tools / 71 skills).
• 2026-04-18 👥 Shadow Account: Extract your strategy rules from a broker journal → backtest the shadow across markets → 8-section HTML/PDF report showing exactly how much you leave on the table (rule violations, early exits, missed signals, counterfactual trades). 4 new tools, 1 skill, 32 tools total. Trade Journal + Shadow Account samples now live in the web UI welcome screen.
• 2026-04-17 📊 Trade Journal Analyzer + Universal File Reader: Upload broker exports (同花顺/东财/富途/generic CSV) → auto trading profile (holding days, win rate, PnL ratio, drawdown) + 4 bias diagnostics (disposition effect, overtrading, chasing momentum, anchoring). read_document now dispatches PDF, Word, Excel, PowerPoint, images (OCR), and 40+ text formats behind one unified call.

Earlier news

• 2026-04-16 🧠 Agent Harness: Persistent cross-session memory, FTS5 session search, self-evolving skills (full CRUD), 5-layer context compression, read/write tool batching. 27 tools, 107 new tests.
• 2026-04-15 🤖 Z.ai + MiniMax: Z.ai provider (#35), MiniMax temperature fix + model update (#33). 13 providers.
• 2026-04-14 🔧 MCP Stability: Fixed backtest tool Connection closed error on stdio transport (#32).
• 2026-04-13 🌐 Cross-Market Composite Backtest: New CompositeEngine backtests mixed-market portfolios (e.g. A-shares + crypto) with shared capital pool and per-market rules. Also fixed swarm template variable fallback and frontend timeout.
• 2026-04-12 🌍 Multi-Platform Export: /pine exports strategies to TradingView (Pine Script v6), TDX (通达信/同花顺/东方财富), and MetaTrader 5 (MQL5) in one command.
• 2026-04-11 🛡️ Reliability & DX: vibe-trading init .env bootstrap (#19), preflight checks, runtime data-source fallback, hardened backtest engine. Multi-language README (#21).
• 2026-04-10 📦 v0.1.4: Docker fix (#8), web_search MCP tool, 12 LLM providers, akshare/ccxt deps. Published to PyPI and ClawHub.
• 2026-04-09 📊 Backtest Wave 2: ChinaFutures, GlobalFutures, Forex, Options v2 engines. Monte Carlo, Bootstrap CI, Walk-Forward validation.
• 2026-04-08 🔧 Multi-market backtest with per-market rules, Pine Script v6 export, 5 data sources with auto-fallback.

---

💡 What Is Vibe-Trading?

Vibe-Trading is an AI-powered multi-agent finance workspace that turns natural language requests into executable trading strategies, research insights, and portfolio analysis across global markets.

Key Capabilities:

• Natural Language → Strategy — Describe an idea; the agent writes, tests, and exports trading code
• 5 Data Sources, Zero Config — A-shares, HK/US, crypto, futures & forex with automatic fallback
• 29 Expert Teams — Pre-built multi-agent swarm workflows for investment, trading & risk
• Cross-Session Memory — Remembers preferences and insights; creates & evolves reusable skills
• 7 Backtest Engines — Cross-market composite testing with statistical validation & 4 optimizers
• Multi-Platform Export — One-click to TradingView, TDX (通达信/同花顺), and MetaTrader 5

---

✨ Key Features

🔍 DeepResearch for Trading • 71 specialist skills with persistent cross-session memory • Self-evolving: agent creates & refines workflows from experience • 5-layer context compression — no info lost in long sessions • Natural-language task routing across all finance domains

🐝 Swarm Intelligence • 29 out-of-the-box trading team presets • DAG-based multi-agent orchestration • Real-time streaming dashboard with live agent status • FTS5 session search across all past conversations

📊 Cross-Market Backtest • A-shares, HK/US equities, crypto, futures & forex • 7 market engines + composite cross-market engine with shared capital pool • Statistical validation: Monte Carlo, Bootstrap CI, Walk-Forward • 15+ performance metrics & 4 optimizers

🧮 Quant Analysis Toolkit • Factor IC/IR analysis & quantile backtesting • Black-Scholes pricing & full Greeks calculation • Technical pattern recognition & detection • Portfolio optimization via MVO/Risk Parity/BL

71 Skills across 7 Categories

• 📊 71 specialized finance skills organized into 7 categories
• 🌐 Complete coverage from traditional markets to crypto & DeFi
• 🔬 Comprehensive capabilities spanning data sourcing to quantitative research

Category	Skills	Examples
Data Source	6	data-routing, tushare, yfinance, okx-market, akshare, ccxt
Strategy	17	strategy-generate, cross-market-strategy, technical-basic, candlestick, ichimoku, elliott-wave, smc, multi-factor, ml-strategy
Analysis	15	factor-research, macro-analysis, global-macro, valuation-model, earnings-forecast, credit-analysis
Asset Class	9	options-strategy, options-advanced, convertible-bond, etf-analysis, asset-allocation, sector-rotation
Crypto	7	perp-funding-basis, liquidation-heatmap, stablecoin-flow, defi-yield, onchain-analysis
Flow	7	hk-connect-flow, us-etf-flow, edgar-sec-filings, financial-statement, adr-hshare
Tool	8	backtest-diagnose, report-generate, pine-script, doc-reader, web-reader

29 Agent Swarm Team Presets

• 🏢 29 ready-to-use agent teams
• ⚡ Pre-configured finance workflows
• 🎯 Investment, trading & risk management 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

_{Plus 20+ additional specialist presets — run vibe-trading --swarm-presets to explore all.}

🎬 Demo

https://github.com/user-attachments/assets/4e4dcb80-7358-4b9a-92f0-1e29612e6e86	https://github.com/user-attachments/assets/3754a414-c3ee-464f-b1e8-78e1a74fbd30
☝️ Natural-language backtest & multi-agent swarm debate — Web UI + CLI

---

🚀 Quick 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 LLM API key from any supported provider — or run locally with Ollama (no key needed)
• Python 3.11+ for Path B
• Docker for Path A

Supported LLM providers: OpenRouter, OpenAI, DeepSeek, Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, Xiaomi MIMO, Z.ai, Ollama (local). See .env.example for config.

Tip: All markets work without any API keys thanks to automatic fallback. yfinance (HK/US), OKX (crypto), and AKShare (A-shares, US, HK, futures, forex) are all free. Tushare token is optional — AKShare covers A-shares as a free fallback.

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 — uncomment your LLM provider and set API key
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 your LLM provider 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

Copy agent/.env.example to agent/.env and uncomment the provider block you want. Each provider needs 3-4 variables:

Variable	Required	Description
LANGCHAIN_PROVIDER	Yes	Provider name (openrouter, deepseek, groq, ollama, etc.)
<PROVIDER>_API_KEY	Yes*	API key (OPENROUTER_API_KEY, DEEPSEEK_API_KEY, etc.)
<PROVIDER>_BASE_URL	Yes	API endpoint URL
LANGCHAIN_MODEL_NAME	Yes	Model name (e.g. deepseek/deepseek-v3.2)
TUSHARE_TOKEN	No	Tushare Pro token for A-share data (falls back to AKShare)
TIMEOUT_SECONDS	No	LLM call timeout, default 120s

_{* Ollama does not require an API key.}

Free data (no key needed): A-shares via AKShare, HK/US equities via yfinance, crypto via OKX, 100+ crypto exchanges via CCXT. The system automatically selects the best available source for each market.

🎯 Recommended Models

Vibe-Trading is a tool-heavy agent — skills, backtests, memory, and swarms all flow through tool calls. Model choice directly decides whether the agent uses its tools or fabricates answers from training data.

Tier	Examples	When to use
Best	anthropic/claude-opus-4.7, anthropic/claude-sonnet-4.6, openai/gpt-5.4, google/gemini-3.1-pro-preview	Complex swarms (3+ agents), long research sessions, paper-grade analysis
Sweet spot (default)	deepseek/deepseek-v3.2, x-ai/grok-4.20, z-ai/glm-5.1, moonshotai/kimi-k2.5, qwen/qwen3-max-thinking	Daily driver — reliable tool-calling at ~1/10 the cost
Avoid for agent use	*-nano, *-flash-lite, *-coder-next, small / distilled variants	Tool-calling is unreliable — the agent will appear to "answer from memory" instead of loading skills or running backtests

The default agent/.env.example ships with deepseek/deepseek-v3.2 — the cheapest option in the sweet-spot tier.

---

🖥 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 71 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
/pine <run_id>	Export indicators (TradingView + TDX + MT5)
/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 --pine <run_id>           # Export indicators (TradingView + TDX + MT5)
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
GET	/runs/{run_id}/pine	Multi-platform indicator export
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 17 MCP tools for any MCP-compatible client. Runs as a stdio subprocess — no server setup needed. 16 of 17 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 (17): list_skills, load_skill, backtest, factor_analysis, analyze_options, pattern_recognition, get_market_data, web_search, 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 71 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 71 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 — 17 tools for OpenClaw / Claude Desktop
│   │
│   ├── src/
│   │   ├── agent/                  # ReAct agent core
│   │   │   ├── loop.py             #   5-layer compression + read/write tool batching
│   │   │   ├── context.py          #   system prompt + auto-recall from persistent memory
│   │   │   ├── skills.py           #   skill loader (71 bundled + user-created via CRUD)
│   │   │   ├── tools.py            #   tool base class + registry
│   │   │   ├── memory.py           #   lightweight workspace state per run
│   │   │   ├── frontmatter.py      #   shared YAML frontmatter parser
│   │   │   └── trace.py            #   execution trace writer
│   │   │
│   │   ├── memory/                 # Cross-session persistent memory
│   │   │   └── persistent.py       #   file-based memory (~/.vibe-trading/memory/)
│   │   │
│   │   ├── tools/                  # 27 auto-discovered agent tools
│   │   │   ├── backtest_tool.py    #   run backtests
│   │   │   ├── remember_tool.py    #   cross-session memory (save/recall/forget)
│   │   │   ├── skill_writer_tool.py #  skill CRUD (save/patch/delete/file)
│   │   │   ├── session_search_tool.py # FTS5 cross-session search
│   │   │   ├── swarm_tool.py       #   launch swarm teams
│   │   │   ├── web_search_tool.py  #   DuckDuckGo web search
│   │   │   └── ...                 #   bash, file I/O, factor analysis, options, etc.
│   │   │
│   │   ├── skills/                 # 71 finance skills in 7 categories (SKILL.md each)
│   │   ├── swarm/                  # Swarm DAG execution engine
│   │   ├── session/                # Multi-turn chat + FTS5 session search
│   │   └── providers/              # LLM provider abstraction
│   │
│   ├── backtest/                   # Backtest engines
│   │   ├── engines/                #   7 engines + composite cross-market engine + options_portfolio
│   │   ├── loaders/                #   5 sources: tushare, okx, yfinance, akshare, ccxt
│   │   │   ├── base.py             #   DataLoader Protocol
│   │   │   └── registry.py         #   Registry + auto-fallback chains
│   │   └── 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

---

🗺 Roadmap

We ship in phases. Items move to Issues when work begins.

Phase	Feature	Status
Agent Harness	Persistent cross-session memory (remember / recall / forget)	Done
	Self-evolving skills — agent creates, patches, and deletes its own workflows	Done
	FTS5 cross-session search across all past conversations	Done
	5-layer context compression (micro → collapse → auto → manual → iterative)	Done
	Read/write tool batching — parallel execution for readonly tools	Done
Next Up	Autonomous research loop — agent iterates hypotheses overnight	In Progress
	IM integration (Slack / Telegram / WeChat)	Planned
Analysis & Viz	Options volatility surface & Greeks 3D visualization	Planned
	Cross-asset correlation heatmap with rolling window & clustering	Planned
	Benchmark comparison in CLI backtest output	Planned
Skills & Presets	Dividend Analysis skill	Planned
	ESG / Sustainable Investing swarm preset	Planned
Portfolio & Optimization	Advanced portfolio optimizer: leverage, sector caps, turnover constraints	Planned
Future	Strategy marketplace (share & discover)	Exploring
	Live data streaming via WebSocket	Exploring

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Good first issues are tagged with good first issue — pick one and get started.

Want to contribute something bigger? Check the Roadmap above and open an issue to discuss before starting.

---

Contributors

Thanks to everyone who has contributed to Vibe-Trading!

---

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 ✨