birdxs/vibe-trading
AI trading agent with backtesting. Includes Telegram & Feishu channels.
7.4K
birdxs/vibe-trading repository overview
English | 中文 | 日本語 | 한국어 | العربية | Español | Bahasa Indonesia
Vibe-Trading: Your Personal Trading Agent
One Command to Empower Your Agent with Comprehensive Trading Capabilities
GitHub topic rankings by stars · Nov 4, 2026
#1 Backtesting ·
#3 Algorithmic Trading ·
#4 Quantitative Finance
Website · Docs · News · Features · Shadow Account · Demo · Quick Start · Examples · API / MCP · Roadmap · Contributors
📰 News
-
2026-11-07 🧪 Research Lab: trading costs and out-of-sample testing — Rerun saved price inputs under different fees and slippage; select parameters using training results only, then freeze them for out-of-sample tests and a separate final holdout. The Research Lab shares Web, CLI, API and Agent/MCP workflows, with all eleven UI languages. Also correct window-boundary returns and factor warmup/long-window calculations, and add 20 offline task-replay cases that keep missing evidence visible. Versioned research artifacts can now store structured financial facts (#2164), and bare Chinese futures contract codes resolve correctly (#2177). On
main, for the next pip release. -
2026-11-06 📈 Implied-volatility grids and paper-trading fixes — Build strike-by-expiry IV grids from supplied option observations, with observed/interpolated labels and no extrapolation (#2172). Extreme numeric inputs now produce finite results or explicit errors. A-share 5m market orders blocked by a price limit are canceled immediately (#2176); the matcher also processes symbols chronologically so later proceeds cannot fund earlier orders. On
main, for the next pip release; public 5m requests still support one symbol per step. -
2026-11-05 🚀 v0.1.19 released (Release notes,
pip install -U vibe-trading-ai): research that outlives the chat — save versioned research artifacts with their evidence and revise them, reuse backtests from earlier turns and sessions, and edit a research goal in place. New opt-ins: a five-minute A-share paper simulation, and Gildata financial queries, stock screening and Shannon portfolio diagnosis (QVeris is removed; an existingGILDATA_TOKENalone now enables nothing). Also Argentina (BYMA) backtests, Parallel web search, Codex OAuth model discovery, and both 0.1.18 regressions fixed. 116 merged pull requests plus 21 landed through maintainer commits, from 26 contributors (CHANGELOG). Fixed today: a backtest reports the benchmark it actually evaluated, long/short books get a risk x-ray, GTJA alpha 17 stays missing while its inputs warm up, the Shannon panel speaks all eleven UI languages, and two reviewed contributor fixes that had not landed are in (#2042 TTM sums across a missing quarter, #1985 3:2 split detection). Thanks @rudycelekli, @he-yufeng, @Jackzigen, @Shizoqua, @cgycorey, @dajiaohuang, @zeus229, @alexwan02, @BHhhh-123, @remote-controlled-man, @shadowinlife, @TWJxi, @lishuanghong1989-netizen, @TerryF7, @davidalmeida90, @DrDLyuan, @goatyyc, @hnq-ai, @kadyrbekovhamit-cyber, @MetaAviator, @octo-patch, @RowanAldean, @VectorPeak, @wavebyrd and @yufengsika! On main after the release (next pip release): backtest benchmarks are bought at the first evaluated open, as the strategy is, instead of from the last warm-up close; excess return no longer includes that move (AAPL 20/60 SMA example: 22.5% → 18.4%).
Earlier news
-
2026-11-04 📊 Gildata financial queries, stock screening and Shannon portfolio diagnosis — Screen stocks by market cap and retrieve their half-year revenue in one request, or inspect portfolio factor exposures and each holding’s contribution to volatility. All nine Gildata features are opt-in, including for existing token holders. Free data sources never fall back to Gildata. #2117 · #2118 · #2119 Also clarified next-bar backtest fills, fixed false Swarm timeouts on Unicode heartbeats and sped up research artifact deduplication. #2137 · #2155 · #2159
-
2026-11-03 🛠️ Runtime integrity and localization follow-ups: Preserve U+2028/U+2029 inside trace, audit-ledger and session-search JSONL records, keep ledger appends valid after such payloads, normalize underscored model labels, and preserve handoff summaries during layer-2 compaction. Also accept BOM-prefixed frontmatter and keep the welcome surface aligned in RTL locales. Add regression coverage.
-
2026-11-02 🛠️ Frontmatter, result safety and welcome polish: Unquote quoted scalar metadata, fall back to a readable truncation when an oversized result cannot be encoded, and refine the welcome layout and featured cards. Add regression coverage.
-
2026-11-01 🛠️ Session timestamps, theme contrast and welcome interactions: Stamp session updates in UTC, keep dark-mode primary buttons legible, and make side-panel examples clickable with clear category labels. Add regression coverage.
-
2026-10-31 🛠️ Welcome and ticker parsing polish: Move the welcome surface to a warm paper palette and two-column layout, make featured examples and side-panel actions clearer, and stop trailing ticker letters from being interpreted as A-share or A/H constraints.
✨ Key Features
💡 What Is Vibe-Trading?
Vibe-Trading turns finance questions into research reports, runnable backtests and paper portfolios. You can also authorize a supported broker to execute live trades within a mandate you set and can halt. Your funds stay with the broker.
✨ What You Can Do
| Task | Where to start |
|---|---|
| Research markets, filings or uploaded documents | Ask in Web chat or attach a report. |
| Backtest a strategy or benchmark alphas | Inspect charts and trades in Run Detail, or compare factors in /alpha-zoo. |
| Simulate trading or replay a journal | Track daily fills and NAV in /paper-trading. Use /journal and /shadow in the CLI to review your trades. |
| Combine accounts or compare allocations | Open /portfolio for holdings and proposed allocation changes. Broker support |
| Explore options and correlations | Open /options for multi-leg payoffs and Greeks, or /correlation for market regimes. |
| Coordinate or repeat research | Run a Swarm team, assign work in Pixel Office or schedule a brief in /scheduled. |
| Revisit research with dated evidence | Search /research-artifacts. Versioned research |
⚡ Quick Example
Once you have run vibe-trading init, you can ask for a backtest in plain English or benchmark an existing alpha library from the terminal.
vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average crossover for 2024. Compare it with buy-and-hold and report maximum drawdown."
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20
Open Run Detail to compare the crossover with buy-and-hold, inspect the trades behind a drawdown and check the data source on the run card.
🧪 Research Workflow
| Step | In the crossover example |
|---|---|
| Plan | Identify the trading pair, date range, moving averages and benchmark from the prompt. |
| Ground | Fetch historical bars for BTC-USDT. Check the source and dates before interpreting the result. |
| Execute | Write the strategy and run the backtest. The run directory holds the strategy, trades and equity curve. |
| Validate | Compare the result with buy-and-hold. Inspect turnover, drawdown and validation warnings alongside return. |
| Revisit | Open the saved run or ask a follow-up with different parameters. You can also save a dated research conclusion and revise it when new evidence arrives. |
📡 Data Sources & Smart Fallback
The loader supports 28 market-data sources. With source: "auto", it infers the market from the symbol and tries the configured sources in order.
| Market | How a request is filled |
|---|---|
| A-shares and Hong Kong | Start with Tencent. If it cannot supply the bars, try Eastmoney and then the remaining sources for that market. |
| US equities | Start with Yahoo. Stooq and Sina are the next two sources in the chain. |
| Crypto | Try OKX, Binance and CCXT before falling back to other sources. |
| Futures | Chinese contracts can use AKShare or local bars. Supply local bars for global contracts. |
You can also choose a source explicitly. For example, installing vibe-trading-ai[ashare] adds the token-free BaoStock loader for daily A-share bars. The data source reference lists the full chains and credential requirements.
🔩 Detailed Capabilities
Market research
| Feature | What you can do |
|---|---|
| Filings and holdings | Compare a manager’s SEC 13F holdings across quarters, or look through an ETF to its underlying positions. Each holdings report carries its reporting date. |
| Company valuation | Use /dcf to see how a valuation changes with the discount rate and terminal growth. Use /comps for peer multiples, or build a linked three-statement model and export the results to Excel. |
| Papers and documents | Search arXiv and OpenAlex for a signal, inspect the authors’ definition, then test it on your own universe. Upload a filing, spreadsheet or slide deck for questions about a specific exhibit. |
| Stock screening | With Gildata enabled, screen companies by market cap and retrieve half-year revenue in one request. Screening and portfolio factor diagnosis each have their own opt-in. |
Quant research
| Feature | What you can do |
|---|---|
| Alpha Zoo | Benchmark signals from Qlib, Alpha101, GTJA and the academic and fundamental libraries. Compare information coefficients across horizons, then check whether the result survives a walk-forward test. |
| Backtest engines | Model A-share price limits, crypto funding or futures margin. Use a shared capital pool for a cross-market strategy and inspect the individual fills behind its returns. |
| Options Lab | Build a spread leg by leg. Compare its expiry payoff with the Greeks and see how the position responds to a change in spot price and implied volatility. |
| Portfolio risk | Inspect drawdowns, estimate value at risk and expected shortfall, or use Brinson attribution to separate allocation from stock selection. The correlation view shows when markets start moving together. |
| Strategy tracking | Register a strategy with its evidence and track how its Sharpe ratio or factor information coefficient changes as new results come in. |
Accounts and trading
| Feature | What you can do |
|---|---|
| Portfolio | Bring read-only broker holdings into one snapshot or import an extraETF export. Enter target weights to preview the value change for each holding. |
| Paper trading | Advance a saved account one trading day and inspect fills, cash and NAV. You can also replay an A-share session in five-minute steps in a separate simulation. |
| Shadow Account | Import your broker’s trade journal, inspect fees and trading habits, then compare the actual trades with a rule-based replay. |
| Broker connections | Set up a connection in the CLI or Web and test it with a read. For supported live profiles, set symbol, order and exposure limits before enabling trading. The kill switch halts live activity. |
Teams and recurring research
| Feature | What you can do |
|---|---|
| Swarm and Pixel Office | Run a bull–bear investment committee or a quant research desk and inspect the workers’ reports. In Pixel Office, assign a task to a teammate and record the result on the shared board. |
| Scheduled briefs | Start from a premarket brief, an earnings tracker or a portfolio checkup. Choose a schedule and send the report to a configured channel such as Slack, Telegram or email. |
| Research history | Search older sessions and reopen a saved run. Save a dated conclusion with its evidence and compare revisions when the investment case changes. |
| Run records | Inspect the data source, model, execution record and metric references behind a backtest. Reopen the saved trades and equity curve to check a reported figure. |
Broker support at a glance
Compare read-only, paper and live support by broker
Read means a dedicated read-only profile. Sim means paper orders through a broker sandbox or local simulation. Live means live orders under a mandate.
Yes indicates a declared capability. A dash means no matching profile is declared.
| Broker | Read | Sim | Live |
|---|---|---|---|
| alpaca | Yes | Yes | Yes |
| binance | Yes | Yes | Yes |
| dhan | Yes | Yes | — |
| etoro | Yes | Yes | Yes |
| futu | Yes | Yes | Yes |
| ibkr | Yes | — | — |
| kis | Yes | Yes | — |
| longbridge | Yes | Yes | — |
| mstock | Yes | — | — |
| mt5 | Yes | Yes | Yes |
| okx | Yes | Yes | Yes |
| robinhood | Yes | — | Yes |
| scalable | Yes | — | — |
| shoonya | Yes | Yes | — |
| tiger | Yes | Yes | Yes |
| toss | Yes | — | — |
| trading212 | Yes | — | — |
| upbit | Yes | Yes | — |
| zerodha | Yes | Yes | — |
🎬 Demo
| Web · From prompt to backtest | CLI · Interactive terminal |
|
https://github.com/user-attachments/assets/2c595ee1-c577-481a-9460-34ea12bcf41c |
https://github.com/user-attachments/assets/ac79426e-f3f7-4349-b0d5-d997a2725784 |
| Send a strategy request, follow the agent’s work and inspect the resulting run. | Browse the research playbooks and open the pre-market brief in the terminal. |
🚀 Quick Start
Terminal. Install the package with Python 3.11+, choose a model provider in the setup wizard, then open the interactive CLI.
pip install vibe-trading-ai
vibe-trading init
vibe-trading
Web app. Docker serves the frontend and API together at http://localhost:8899. From a fresh checkout, configure your provider before starting the container.
git clone https://github.com/HKUDS/Vibe-Trading.git
cd Vibe-Trading
cp agent/.env.example agent/.env
# Set your provider and API key in agent/.env.
docker compose up --build
The PyPI package includes the CLI, API and MCP server. For a frontend development setup or a local model, see the installation guide.
🖥 CLI Reference
Start vibe-trading for the interactive terminal. Type /help at the prompt to browse commands or use these shortcuts during research.
| Command | Use it to |
|---|---|
/model | Switch the provider or model for the session. |
/history | Browse and resume a prior conversation. |
/show <run-id> | Inspect the results of a saved run. |
/pine | Export the current strategy as a Pine Script indicator. |
From the shell, vibe-trading alpha list browses the factor libraries and vibe-trading playbook list shows the scheduled research templates.
💡 Examples
- Compare stocks. Ask “Compare AAPL and MSFT over 2024. Which month accounts for the largest gap in returns?” Resume the conversation later with
/history. - Review your trades. Use
/journalto analyze your exported trade history, then/shadowto compare your trades with a rule-based alternative. - Run an investment committee. Choose a stock and follow the bull and bear cases through to the final report.
vibe-trading --swarm-run investment_committee '{"target":"TSLA","market":"US"}'
🌐 API Server
Start a local server with vibe-trading serve --port 8899. In a second terminal, run curl http://localhost:8899/runs to list saved runs. Use the returned ID with GET /runs/{run_id} to inspect its results.
| To run a research session over HTTP | Endpoint |
|---|---|
| Create the conversation | POST /sessions |
| Send the research question | POST /sessions/{id}/messages |
| Follow progress as it happens | GET /sessions/{id}/events |
Open http://localhost:8899/docs to try the endpoints interactively. Authenticated clients send the API key in the Authorization: Bearer header.
🔌 MCP Plugin
MCP clients can launch the same package over stdio. Add this entry to Claude Desktop’s claude_desktop_config.json, restart the client and call list_skills.
{
"mcpServers": {
"vibe-trading": { "command": "vibe-trading-mcp" }
}
}
For other clients or a custom output directory, see the MCP configurations.
🏛 Ecosystem
Vibe-Trading is part of the HKUDS agent ecosystem:
|
NanoBot Ultra-Lightweight Personal AI Assistant |
AI-Trader Agent-Native Signal & Copy Trading Platform |
CLI-Anything Making All Software Agent-Native |
OpenSpace Self-Evolving AI Agent Skills |
ClawTeam Agent Swarm Intelligence |
🗺 Roadmap
| Area | Available now | Next |
|---|---|---|
| Paper trading | Daily accounts persist cash, fills and NAV between sessions. A separate simulation replays an A-share session in five-minute steps. | Opt-in volume-share matching (#2128, draft). |
| Research | Run cards record metrics and evidence for a completed backtest. Dated research artifacts keep revision history and are searchable. | Structured financial facts in research artifacts (#2164, in review). |
| Options Lab | Explore multi-leg payoffs, Greeks and spot × IV scenarios. | Volatility surface planned. |
Contributing
Pick a good first issue or open an issue to discuss a larger change. The contributing guide covers local setup and checks to run before opening a pull request.
Contributors
Thank you to everyone w
Tag summary
Content type
Image
Digest
sha256:7dec533c9…
Size
488.1 MB
Last updated
about 11 hours ago
docker pull birdxs/vibe-trading