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](https://github.com/HKUDS/Vibe-Trading/pull/35)), MiniMax temperature fix + model update ([#33](https://github.com/HKUDS/Vibe-Trading/pull/33)). 13 providers. - **2026-04-14** 🔧 **MCP Stability**: Fixed backtest tool `Connection closed` error on stdio transport ([#32](https://github.com/HKUDS/Vibe-Trading/pull/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](https://github.com/HKUDS/Vibe-Trading/pull/19)), preflight checks, runtime data-source fallback, hardened backtest engine. Multi-language README ([#21](https://github.com/HKUDS/Vibe-Trading/pull/21)). - **2026-04-10** 📦 **v0.1.4**: Docker fix ([#8](https://github.com/HKUDS/Vibe-Trading/issues/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) ```bash 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.) | ```bash 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) ```bash 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 ```bash 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)

```bash # 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):** ```bash cd frontend && npm run build && cd .. vibe-trading serve --port 8899 # FastAPI serves dist/ as static files ```

### Path C: MCP plugin See [MCP Plugin](#-mcp-plugin) section below. ### Path D: ClawHub (one command) ```bash npx clawhub@latest install vibe-trading --force ``` The skill + MCP config is downloaded into your agent's skills directory. See [ClawHub install](#-mcp-plugin) 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.) | | `_API_KEY` | Yes* | API key (`OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`, etc.) | | `_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 ```bash 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 [vars_json]` | Run a swarm team with live streaming | | `/swarm list` | Swarm run history | | `/swarm show ` | Swarm run details | | `/swarm cancel ` | Cancel a running swarm | | `/list` | Recent runs | | `/show ` | Run details + metrics | | `/code ` | Generated strategy code | | `/pine ` | Export indicators (TradingView + TDX + MT5) | | `/trace ` | Full execution replay | | `/continue ` | Continue a run with new instructions | | `/sessions` | List chat sessions | | `/settings` | Show runtime config | | `/clear` | Clear screen | | `/quit` | Exit |

Single run & flags

```bash 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 ``` ```bash 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 vibe-trading --code vibe-trading --pine # Export indicators (TradingView + TDX + MT5) vibe-trading --trace vibe-trading --continue "refine the strategy" vibe-trading --upload report.pdf ```

--- ## 🌐 API Server ```bash 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`: ```json { "mcpServers": { "vibe-trading": { "command": "vibe-trading-mcp" } } } ```

OpenClaw

Add to `~/.openclaw/config.yaml`: ```yaml skills: - name: vibe-trading command: vibe-trading-mcp ```

Cursor / Windsurf / other MCP clients

```bash 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)

```bash 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](https://clawhub.ai/skills/vibe-trading)

OpenSpace — self-evolving skills

All 71 finance skills are published on [open-space.cloud](https://open-space.cloud) and evolve autonomously through OpenSpace's self-evolution engine. To use with OpenSpace, add both MCP servers to your agent config: ```json { "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](https://github.com/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](https://github.com/HKUDS/Vibe-Trading/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](CONTRIBUTING.md) for guidelines. **Good first issues** are tagged with [`good first issue`](https://github.com/HKUDS/Vibe-Trading/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — pick one and get started. Want to contribute something bigger? Check the [Roadmap](#-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](LICENSE) ---

Thanks for visiting Vibe-Trading ✨

36 Trending Projects