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-05-08 🧾 Tushare statement fields in filters: A-share daily backtests can now request PIT-safe financial statement fields through fundamental_fields, so signal engines can screen on income_total_revenue, income_n_income, balancesheet_total_hldr_eqy_exc_min_int, fina_indicator_roe, and similar table-prefixed columns after their announcement/disclosure dates (#76, thanks @mrbob-git). Follow-up hardening makes explicit statement-field requests fail fast if Tushare enrichment cannot run, instead of silently falling back to raw price bars (#77).
• 2026-05-07 📈 Tushare fundamentals + community triage: Added a point-in-time TushareFundamentalProvider contract for fundamental research workflows, with regression coverage for the project TUSHARE_TOKEN environment path (#74). Community triage also clarified that Vibe-Trading keeps rapid iteration focused on one UI language for now, avoids adding redundant search dependencies while DuckDuckGo-backed web_search is already bundled, and treats unofficial hosted deployments as untrusted places for API keys or data-source tokens.
• 2026-05-06 🚀 v0.1.7 released (Release notes, pip install -U vibe-trading-ai): Security-boundary hardening is now published on PyPI and ClawHub, covering safer API/read/upload/file/URL/generated-code/shell-tool/Docker defaults while keeping localhost CLI/Web UI workflows low-friction. This cycle also includes Web UI Settings, correlation heatmap, OpenAI Codex OAuth, A-share pre-ST filtering, interactive CLI UX, swarm preset inspection, dividend analysis, dev workflow polish, and audited frontend build-dependency floors. Thanks to the 0.1.7 contributors and to lemi9090 (S2W) for coordinated security validation.

💡 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
• 6 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 • 74 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

74 Skills across 8 Categories

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

29 Agent Swarm Team Presets

• 🏢 29 ready-to-use agent teams
• ⚡ Pre-configured finance workflows
• 🎯 Investment, trading & risk management presets

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

🎬 Demo

🚀 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

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
• OpenAI Codex can also be used with ChatGPT OAuth: set LANGCHAIN_PROVIDER=openai-codex, then run vibe-trading provider login openai-codex. This does not use OPENAI_API_KEY.

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.

Docker publishes the backend on 127.0.0.1:8899 by default and runs the app as a non-root container user. If you intentionally expose the API beyond your own machine, set a strong API_AUTH_KEY and send Authorization: Bearer <key> from clients.

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

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

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

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:

_{* Ollama does not require an API key. OpenAI Codex uses ChatGPT OAuth and stores tokens via oauth-cli-kit, not in agent/.env.}

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.

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

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

💡 Examples

Strategy & Backtesting

# Moving average crossover on US equities
vibe-trading run -p "Backtest a 20/50-day moving average crossover on AAPL for the past year, show Sharpe ratio and max drawdown"

# RSI mean-reversion on crypto
vibe-trading run -p "Test RSI(14) mean-reversion on BTC-USDT: buy below 30, sell above 70, last 6 months"

# Multi-factor strategy on A-shares
vibe-trading run -p "Backtest a momentum + value + quality multi-factor strategy on CSI 300 constituents over 2 years"

# After backtesting, export to TradingView / TDX / MetaTrader 5
vibe-trading --pine <run_id>

Market Research

# Equity deep-dive
vibe-trading run -p "Research NVDA: earnings trend, analyst consensus, option flow, and key risks for next quarter"

# Macro analysis
vibe-trading run -p "Analyze the current Fed rate path, USD strength, and impact on EM equities and gold"

# Crypto on-chain
vibe-trading run -p "Deep dive BTC on-chain: whale flows, exchange balances, miner activity, and funding rates"

Swarm Workflows

# Bull/bear debate on a stock
vibe-trading --swarm-run investment_committee '{"topic": "Is TSLA a buy at current levels?"}'

# Quant strategy from screening to backtest
vibe-trading --swarm-run quant_strategy_desk '{"universe": "S&P 500", "horizon": "3 months"}'

# Crypto desk: funding + liquidation + flow → risk manager
vibe-trading --swarm-run crypto_trading_desk '{"asset": "ETH-USDT", "timeframe": "1w"}'

# Global macro portfolio allocation
vibe-trading --swarm-run macro_rates_fx_desk '{"focus": "Fed pivot impact on EM bonds"}'

Cross-Session Memory

# Save your preferences once
vibe-trading run -p "Remember: I prefer RSI-based strategies, max 10% drawdown, hold period 5–20 days"

# The agent recalls them in future sessions automatically
vibe-trading run -p "Build a crypto strategy that fits my risk profile"

Upload & Analyze Documents

# Analyze a broker export or earnings report
vibe-trading --upload trades_export.csv
vibe-trading run -p "Profile my trading behavior and identify any biases"

vibe-trading --upload NVDA_Q1_earnings.pdf
vibe-trading run -p "Summarize the key risks and beats/misses from this earnings report"

🌐 API Server

vibe-trading serve --port 8899

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

Security defaults

For localhost development, vibe-trading serve keeps the browser workflow simple. For any non-local client, sensitive API endpoints require API_AUTH_KEY; use Authorization: Bearer <key> for JSON/upload requests. Browser EventSource streams are handled by the Web UI after you enter the same key once in Settings.

Shell-capable tools are available to local CLI and trusted localhost workflows, but are not exposed to remote API sessions unless you explicitly set VIBE_TRADING_ENABLE_SHELL_TOOLS=1. Document and journal readers are limited to upload/import roots by default; place files under agent/uploads, agent/runs, ./uploads, ./data, ~/.vibe-trading/uploads, or ~/.vibe-trading/imports, or add a dedicated directory through VIBE_TRADING_ALLOWED_FILE_ROOTS.

Web UI Settings

The Web UI Settings page lets local users update the LLM provider/model, base URL, generation parameters, reasoning effort, and optional market data credentials such as the Tushare token. Settings are persisted to agent/.env; provider defaults are loaded from agent/src/providers/llm_providers.json.

Settings reads are side-effect free: GET /settings/llm and GET /settings/data-sources never create agent/.env, and they only return project-relative paths. Settings reads and writes can expose credential state or update credentials/runtime environment, so they require API_AUTH_KEY when configured. If API_AUTH_KEY is unset for dev mode, settings access is accepted only from loopback clients.

🔌 MCP Plugin

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

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

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

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

MCP tools exposed (22): list_skills, load_skill, backtest, factor_analysis, analyze_options, pattern_recognition, get_market_data, web_search, read_url, read_document, read_file, write_file, analyze_trade_journal, extract_shadow_strategy, run_shadow_backtest, render_shadow_report, scan_shadow_signals, list_swarm_presets, run_swarm, get_swarm_status, get_run_result, list_runs.

npx clawhub@latest install vibe-trading --force

{
  "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"
    }
  }
}

📁 Project Structure

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 — 22 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 (74 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/                 # 74 finance skills in 8 categories (SKILL.md each)
│   │   ├── swarm/                  # Swarm DAG execution engine
│   │   │   └── presets/            #   29 swarm preset YAML definitions
│   │   ├── session/                # Multi-turn chat + FTS5 session search
│   │   └── providers/              # LLM provider abstraction
│   │
│   └── backtest/                   # Backtest engines
│       ├── engines/                #   7 engines + composite cross-market engine + options_portfolio
│       ├── loaders/                #   6 sources: tushare, okx, yfinance, akshare, ccxt, futu
│       │   ├── base.py             #   DataLoader Protocol
│       │   └── registry.py         #   Registry + auto-fallback chains
│       └── optimizers/             #   MVO, equal vol, max div, risk parity
│
├── 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:

🗺 Roadmap

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

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!

Recent v0.1.7 cycle contributors and credits:

• @GTC2080 / TaoMu — Web UI Settings and provider/data-source configuration APIs (#57)
• @BigNounce90 — validation CLI hardening for backtest run_dir input (#60)
• @shadowinlife — A-share pre-ST filter skill (#63)
• @MB-Ndhlovu — correlation heatmap dashboard and review fixes (#64, #66)
• @ykykj — OpenAI Codex OAuth provider option (#65)
• @RuifengFu — interactive CLI live status bar and prompt editing (#69)
• @SiMinus — swarm preset inspection command (#73)
• @warren618 / Haozhe Wu — security hardening, release integration, docs, Docker, packaging, and local dev workflow
• lemi9090 (S2W) — coordinated security research, validation, and disclosure support

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

Star History

Thanks for visiting Vibe-Trading ✨