Vibe-Trading: Connecting Natural-Language Research, Backtesting, and Trading Tools to AI Agents

Vibe-Trading moves trading research beyond “ask the model for a few paragraphs of analysis” into a reproducible pipeline of data, tools, backtests, and reports.

What Is Vibe-Trading?

Vibe-Trading is an open-source AI Agent workspace for trading research. It organizes natural-language questions, market data, strategy generation, backtesting, reports, MCP tools, and research memory into a single workflow. It works best as a reproducible research console—not as an automatic money-making tool.

When Is Vibe-Trading a Good Fit?

• Turn trading ideas into runnable backtest tasks quickly.
• Let multiple Agents collaborate on investment, quant, risk, macro, or crypto research themes.
• Import personal trade history, analyze behavioral biases, and generate Shadow Account comparison reports.
• Expose trading research capabilities to Agent workflows via MCP in Claude Desktop, Cursor, OpenClaw, and similar clients.

What Problem Does It Solve?

Traditional AI trading tools often stop at generating analysis text or strategy code. Vibe-Trading tries to complete the loop: start from a natural-language question, choose data sources and tools, generate or invoke strategies and analysis, run backtests, and output metrics, reports, and reusable artifacts.

A typical flow looks like this:

1. The user asks a research question in natural language.
2. The Agent selects the appropriate data sources, tools, or team preset.
3. The system loads market data and context.
4. Strategies are generated or backtesting and analysis tools are invoked.
5. Returns, drawdowns, benchmark comparisons, validation reports, and run logs are produced.

Core Capabilities

• Natural-language trading research: market research, strategy drafts, file and web analysis, and memory-aware workflows.
• Multi-Agent teams: built-in presets for investment, quant, crypto, macro, and risk research teams.
• Cross-market data: A-shares, Hong Kong stocks, US equities, crypto, futures, FX, and local data sources.
• Backtesting and reports: portfolio backtests, data fallback, validation artifacts, and result summaries.
• Shadow Account: extract behavioral patterns from real trade records and compare them against rule-based shadow strategies.
• Alpha Zoo: a collection of quantitative factors for IC, IR, and factor effectiveness analysis.
• MCP Server: expose data, backtesting, reporting, and Shadow Account capabilities to external Agent clients.

Quick Install

pip install vibe-trading-ai

Common entry points:

vibe-trading       # Interactive CLI / TUI
vibe-trading serve # Start FastAPI web service
vibe-trading-mcp   # Start MCP server

Initialize and run an example:

vibe-trading init
vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024 and summarize return and drawdown"

If you hit dependency or import issues after upgrading an older version, rebuild the virtual environment or force reinstall:

pip install --force-reinstall vibe-trading-ai

Docker Deployment

git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
cp agent/.env.example agent/.env
# Edit agent/.env to set LLM provider and API key
docker compose up --build

If the container needs to reach Ollama on the host machine, a common address is:

http://host.docker.internal:11434

Local Development Setup

git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp agent/.env.example agent/.env
vibe-trading

Activate the virtual environment on Windows PowerShell:

.\.venv\Scripts\Activate.ps1

Start the backend and frontend:

vibe-trading serve --port 8899
cd frontend
npm install
npm run dev

Environment Variables

The project requires an LLM provider. Supported providers mentioned in the source material include OpenRouter, OpenAI, DeepSeek, Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, Xiaomi MIMO, Z.ai, and local Ollama.

Common configuration keys:

LANGCHAIN_PROVIDER
<PROVIDER>_API_KEY
<PROVIDER>_BASE_URL
LANGCHAIN_MODEL_NAME
TUSHARE_TOKEN
TIMEOUT_SECONDS
API_AUTH_KEY
VIBE_TRADING_ENABLE_SHELL_TOOLS
VIBE_TRADING_ALLOWED_FILE_ROOTS
VIBE_TRADING_ALLOWED_RUN_ROOTS
CONTENT_FILTER_WARNING_THRESHOLD

The project also supports the OpenAI Codex OAuth path:

vibe-trading provider login openai-codex

Data Sources and Fallback

Vibe-Trading’s data loading layer is one of its practical strengths. It covers multiple market data sources and supports a fallback approach: when the primary source is unavailable or missing, the system can try alternate sources, reducing the chance that a single data provider blocks the research flow.

When integrating in production, verify:

• Data source permissions and tokens are valid.
• Symbols, date ranges, frequency, and adjustment conventions match your research assumptions.
• Backtests do not suffer from look-ahead bias, survivorship bias, or inconsistent data splits.
• Key results can be reproduced from logs and artifacts.

Backtesting and Research Workflow

Example research question:

vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024, summarize return and drawdown, then export the report"

Factor benchmark example:

vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20

These features work well as quick research entry points: validate a hypothesis first, then decide whether to move into stricter quant research, auditing, and production workflows.

Shadow Account

Shadow Account is not about starting from an ideal strategy—it reverse-engineers behavioral patterns from real trade records.

Example:

vibe-trading --upload trades_export.csv
vibe-trading run -p "Analyze my trading behavior, extract my shadow strategy, and compare it with my actual trades"

It can be used to:

• Read broker-exported trade records.
• Analyze holding period, win rate, profit/loss ratio, and drawdown.
• Detect behavioral biases such as disposition effect, overtrading, momentum chasing, and anchoring.
• Compare rule-based shadow strategies against actual trade paths to spot early exits, missed signals, or rule violations.

The safer use case is post-trade review and behavioral diagnosis—not live trading instructions.

MCP and Agent Integration

Vibe-Trading can run as an MCP server, exposing market data, backtesting, report generation, Shadow Account, and related capabilities to MCP-compatible clients. For users already on Claude Desktop, Cursor, or other Agent workflows, this is often more natural than opening a separate app.

Recent Updates

Recent changes suggest the project is strengthening security boundaries, runtime isolation, and data capabilities:

• 2026-07-02: Faster factor computation; backtest subprocesses inherit only allowlisted environment variables, reducing secret exposure.
• 2026-07-01: Tighter defaults for API, Docker, and frontend dev configs; frontend dependency and CSP alert fixes.
• 2026-06-30: A single Agent session runtime can connect to multiple message channels.
• 2026-06-29: Broker-agnostic live advisory safety; Trading 212 read-only connector added.
• 2026-06-19: v0.1.10 expands the global data layer and adds more read-only data tools.

Who It’s For

• Developers who want to plug trading research into MCP or Agent workflows.
• Technical users who want to quickly evaluate multi-market data sources, Alpha Zoo, and Swarm research teams.
• Traders who want behavioral post-mortems from real trade records.
• Quant researchers who want to validate ideas in natural language before committing to heavier pipelines.

Who It’s Not For

• Anyone expecting guaranteed returns from the tool itself.
• Anyone planning live automation without risk limits, human review, and audit mechanisms.
• Anyone who needs a production-grade trading system but won’t verify data, execution, permissions, and failure boundaries themselves.

Risk Disclaimer

Backtest results are not return guarantees, and Agent output is not investment advice. Any live trading should include human review, access controls, risk limits, audit logs, and a kill switch.

Summary

Vibe-Trading’s value is turning trading research from “ask the model for analysis” into a reproducible flow built from data, tools, backtests, reports, and memory. Start with the smallest read-only path: run one local CLI backtest and inspect data sources and report quality. Then explore Shadow Account, Alpha Zoo, MCP, web deployment, or broker connectors as needed.