Vibe-Trading: connecting natural-language research, backtesting, and trading tools to an AI Agent

Fri, 03 Jul 2026 09:58:13 +0800

HKUDS/Vibe-Trading is an open-source AI Agent workspace for trading research. Its positioning is direct: one command gives an agent a broad set of trading research capabilities. It combines natural-language questions, market-data loading, strategy generation, backtesting, reports, MCP tools, and persistent research memory. The goal is not to magically make money for you, but to turn research questions into runnable, inspectable, reviewable analysis workflows.

More precisely, Vibe-Trading fits three kinds of work. First, it can turn a trading idea into a backtest task quickly. Second, it can let multi-agent teams research investing, quant, risk, crypto, and macro topics. Third, it can import your own trading records, analyze behavioral bias, and generate a Shadow Account comparison report. It also supports broker connectors and limited order-placement capabilities, but that part must be treated with strict boundaries: the project does not custody funds, execution happens through brokers you authorize, and you need to understand risk, permissions, and audit mechanisms before using it.

This article breaks the project down from the perspective of developers and quant research users.

What problem Vibe-Trading solves

Many AI trading tools stop at “let the model write an analysis” or “generate a strategy code snippet.” Vibe-Trading tries to complete more of the loop: understand the question, choose data sources, fetch market context, generate or call tools, run backtests, output metrics and reports, and preserve the process for later follow-up.

The workflow roughly looks like this:

The user asks a question in natural language, such as “backtest a BTC-USDT 20/50 moving-average strategy.”
The agent selects relevant skills, tools, data sources, or a swarm preset.
The data-loading layer pulls A-share, HK, US, crypto, futures, forex, or local data.
The system generates testable strategy code and calls the matching backtest or analysis tools.
It outputs returns, drawdown, benchmark comparison, validation reports, run cards, and reusable artifacts.

That makes it closer to a trading research console than a plain chatbot.

Core capabilities

The project README groups its capabilities into several major modules:

Self-improving trading agent: natural-language market research, strategy drafts, file and web analysis, and memory-backed workflows.
Multi-agent trading teams: built-in presets for investment, quant, crypto, macro, and risk teams, with runtime progress and persisted reports.
Cross-market data and backtesting: A-share, HK, US, crypto, futures, and forex coverage, with data fallback, composite backtests, PIT data, and validation artifacts.
Shadow Account: extract behavior patterns from real trade records, generate a rule-based shadow strategy, and compare it with actual trading paths.
Alpha Zoo: hundreds of built-in quant factors that can be evaluated with one command for IC, IR, alive/reversed/dead categorization.
MCP integration: expose trading research capabilities to clients such as Claude Desktop, Cursor, and OpenClaw that support MCP.

These capabilities are broad. For a first integration, do not enable everything at once. A steadier path is to run a natural-language backtest first, then evaluate data sources, reports, Shadow Account, and MCP integration.

Quick install

The simplest route is installing the PyPI package:

`1`	`pip install vibe-trading-ai`

After installation, you get three main commands:

1
2
3

vibe-trading      # interactive CLI / TUI
vibe-trading serve # start the FastAPI web service
vibe-trading-mcp  # start the MCP server

For a first run:

1
2

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 are upgrading from an older version, the README notes that 0.1.10 moved to LangChain 1.x. If imports break after an in-place upgrade, recreate the virtual environment or run:

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

Docker path

For a quick trial, use Docker:

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

Then open:

`1`	`http://localhost:8899`

Docker publishes the backend at 127.0.0.1:8899 by default and runs as a non-root container user. Keep those security defaults. If you intentionally expose the API to a LAN or the public internet, set a strong API_AUTH_KEY, and send:

`1`	`Authorization: Bearer <your-api-key>`

If the app inside Docker needs to reach Ollama on the host, do not use localhost:11434. Inside the container, localhost means the container itself. The project defaults to:

`1`	`http://host.docker.internal:11434`

Local development install

If you want to modify code or use the full CLI locally, install from source:

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

On Windows PowerShell, activate the virtual environment with:

`1`	`.\.venv\Scripts\Activate.ps1`

The Web UI can be started separately:

`1`	`vibe-trading serve --port 8899`

For the frontend dev server:

1
2
3

cd frontend
npm install
npm run dev

The default frontend URL is:

`1`	`http://localhost:5899`

Environment variables

Vibe-Trading needs an LLM provider. The README lists OpenRouter, OpenAI, DeepSeek, Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, Xiaomi MIMO, Z.ai, and local Ollama.

Common environment variables include:

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

API_AUTH_KEY is important for network deployments. VIBE_TRADING_ENABLE_SHELL_TOOLS should be enabled carefully because it involves shell-capable tools. A normal local research workflow does not need high-risk capabilities turned on at the start.

The project also supports the OpenAI Codex OAuth path:

`1`	`vibe-trading provider login openai-codex`

This uses ChatGPT OAuth instead of OPENAI_API_KEY.

Data sources and fallback

One useful part of Vibe-Trading is its data-loading layer. The README says the project currently has 18 market-data sources, covering:

A-share: tencent, mootdx, eastmoney, baostock, akshare, tushare, local
US equities: yahoo, stooq, sina, eastmoney, yfinance, tiingo, fmp, finnhub, alphavantage, akshare, local
HK equities: eastmoney, yahoo, futu, yfinance, akshare, local
Crypto: okx, ccxt, yfinance, local
Futures, funds, macro, and forex: mainly through tushare, akshare, and local

With source: "auto", the loader falls back by market and IP-ban risk. For ordinary users, this is much easier than manually handling the availability of every source. For serious research, you should still record the actual data source, time range, adjustment method, and missing-data handling logic.

If you have your own historical data, use the local: prefix to connect CSV, Parquet, or DuckDB data. Note that Vibe-Trading’s loader layer is for point-in-time historical bars, not real-time ticks or order-book depth. Real-time trading and quotes should go through broker connectors.

Backtesting and research flow

The most common use is turning a research question into a runnable flow:

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

For the built-in Alpha Zoo, run a factor bench directly:

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

The point is not to replace a rigorous quant platform. It is a fast research entry point: run the hypothesis first, then decide whether the result deserves stricter research, audit, and productionization.

Shadow Account: infer behavior patterns from trade records

Shadow Account is one of Vibe-Trading’s more distinctive features. It starts from your real trading records instead of an idealized strategy:

1
2

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"

A typical flow includes:

Read broker-exported trade records, such as Tonghuashun, Eastmoney, Futu, or generic CSV.
Generate a behavior profile: holding days, win rate, PnL ratio, drawdown, disposition effect, overtrading, momentum chasing, anchoring, and related checks.
Extract repeated entry and exit rules.
Run a rule-based Shadow Account backtest and highlight rule breaks, early exits, missed signals, and alternative trade paths.
Output an HTML/PDF report for review and archiving.

This is better for discovering systematic bias in your trading behavior than for issuing the next trade instruction. It is steadier as a review tool than as a real-time decision engine.

MCP and Agent integration

Vibe-Trading can run as an MCP server:

`1`	`vibe-trading-mcp`

That means you can attach it to MCP-capable clients and expose market data, backtesting, report generation, Shadow Account, and similar capabilities as tools for an existing agent. For people already using Claude Desktop, Cursor, or other agent workflows, this is more natural than opening a separate app.

MCP integration also expands the permission surface. File reads, generated code, shell tools, broker connectors, and API keys all need clear boundaries. In remote deployments, confirm API_AUTH_KEY, allowed file roots, run roots, and shell-tool switches.

Recent updates worth noting

The Vibe-Trading README changes frequently. A few recent updates suggest the project is moving from “it runs” toward clearer boundaries and more stable runtime behavior:

2026-07-02: factor calculation acceleration, and generated backtest subprocesses inherit only an allowlisted environment, reducing parent-process secrets exposure.
2026-07-01: tighter API, Docker, and frontend development defaults, plus frontend dependency and CSP fixes.
2026-06-30: the same agent session runtime can attach to 16 message channels, including Telegram, Slack, Discord, Matrix, WhatsApp, Feishu, DingTalk, Teams, and email.
2026-06-29: broker-agnostic live advisory safety and a read-only Trading 212 connector.
2026-06-19: v0.1.10 expanded the global data layer to 18 market-data sources and 18 read-only data tools.

Projects like this can become dangerous when capabilities grow faster than boundaries. The recent updates show work on security, runtime isolation, data fallback, frontend state, and message channels. Those are more important than simply piling on features.

Who it is for, and who it is not for

Vibe-Trading is suitable for:

Quant researchers who want to generate research and backtesting flows from natural language.
Developers who want to connect trading research capabilities into MCP / Agent workflows.
Individual investors who want to review their own trade records and identify behavioral bias.
Technical users evaluating multi-market data sources, Alpha Zoo, and swarm research teams.

It is not suitable for:

Users expecting “automatic profits out of the box.”
People who do not understand data quality, backtest bias, and trading risk.
Anyone who wants to connect unaudited strategies directly to real-money accounts.
Users unwilling to configure API keys, permission boundaries, and a local environment.

One reminder matters: backtest results are not return guarantees, and agent output is not investment advice. Any live-trading behavior should have human review, risk limits, audit records, and an instant stop mechanism.

Summary

Vibe-Trading’s value is moving trading research from “the model writes a few paragraphs” to “data, tools, backtests, reports, and memory form a reviewable workflow.” Its scope is broad: natural-language research, multi-agent teams, cross-market data, Alpha Zoo, Shadow Account, Web UI, CLI, MCP, and broker connectors all live in one project.

In real use, start with the smallest path: run a read-only local CLI backtest, then inspect whether the data sources and report match expectations. Next, try Shadow Account or Alpha Zoo. Only after that should you consider MCP, Web deployment, and broker connectors. The most expensive mistakes in trading systems are often not about what a tool cannot do, but about users failing to define permission, data, risk, and audit boundaries clearly.

Backtesting on KnightLi Blog