English | 中文 | 日本語 | 한국어 | العربية | Español
Vibe-Trading: Your Personal Trading Agent
One Command to Empower Your Agent with Comprehensive Trading Capabilities
Website · Docs · News · Features · Shadow Account · Demo · Quick Start · Examples · API / MCP · Roadmap · Contributing
📰 News
⚠️ Security warning: The X account
VibeTrading_HKU, Virtuals project101845, and token contract0x640BDBF77b6447E8b7DB7894cED84BD1c40571f4are not official Vibe-Trading assets. We have never launched or endorsed any token or memecoin. Do not buy, connect a wallet, or sign anything. Details.
- 2026-08-15 🛡️ Safer desktop updates, reliable Windows packaging, and factor research in Run Detail: The dormant updater boundary now retains owned-process evidence for cleanup retries, probes TCP listeners instead of HTTP health, reserves recovery journals atomically, binds Authenticode and hashes to the same staged bytes, and rechecks immediately before launch (#1101). Windows packaging now owns bounded, checksum-verified Electron downloads and extracts the pinned GTK asset as data through 7-Zip instead of executing its flaky legacy installer; native Windows CI covers exit codes, timeouts, runtime assembly, NSIS, and packaged startup (#1104, closes #1093). Run Detail gains IC series and statistics, quantile equity, and IC correlation with bounded artifact traversal and finite JSON payloads (#1099, closes #1100); universal hash locks are verified natively on Linux, macOS ARM64, and Windows (#1102, closes #1089). Thanks @QCYTSN and @shadowinlife!
- 2026-08-14 ⚙️ A reasoning setting that did nothing, and runs that stopped while they could still recover:
LANGCHAIN_REASONING_EFFORTwas silently a no-op for almost every provider — only direct OpenAI ever received it, so settinghighon DeepSeek changed nothing and said so nowhere. Effort now reaches both transports through each adapter's own field: Chat Completions by default, the Responses API whenLANGCHAIN_USE_RESPONSES_API=true. The providers given a top-levelreasoning_effortare a verified allowlist rather than everything that speaks the OpenAI wire format — an endpoint that validates its request body strictly rejects an unknown key and fails the call, so the cost of guessing wrong is every request, not a missing setting (#1025). The grounding gate also stops handing back "confirm and continue" while a deterministic read-only recovery is still available: an unresolved instrument now drivessearch_symbol→get_market_dataon its own bounded budget instead of spending the run's iterations and failing closed (#1092, closes #1081). New: an Options Lab page — multi-leg payoff diagram, spot × IV scenario matrix, portfolio Greeks and a live chain, computed by the existing payoff tool andquantlibrather than a second implementation of the math (#1096); a backtest tearsheet tab with a monthly-returns heatmap, annual returns and top-N drawdown episodes (#1091); tickerall as the 25th market-data source — hosted MetaTrader 5 forex/metals bars with no local terminal on any OS, explicit-only so a broker key is never a silent fallback target, and a truncated history window is an error rather than a quietly short series (#968, closes #897); and Novita AI plus GitHub Copilot as built-in providers (#1059, #990). eToro gains asset-class browsing by instrument type, and copy trading now refuses a demo account with a stated reason instead of failing obscurely (#1070). Thanks @cgycorey, @Shizoqua, @shadowinlife, @miguelangelo78, @jax-novita, @sykuang, and @ofeksh-tr. - 2026-08-13 🎯 Backtest reports show the book that actually filled:
positions.csvheld the optimiser's target weights, so a report could claim 80% exposure while lot rounding, fees, or a blocked order left the portfolio near 20% — and those targets also fed the invested-weight metrics and the risk x-ray. Fills now go topositions.csv, requests totarget_positions.csv(#1082). Run Detail gains a research dashboard at?view=dashboard(#1084), and Spanish is the sixth UI language (#1087). Also:get_research_reportswas returning HTTP 400 for every A-share symbol (#1077); IBKR quotes separate the tier requested from the one applied (#1075);.env.partialis written atomically (#1086); the Docker workflow pins actions to commits and hash-locks channel SDKs (#1088); and the grounding gate stops reading support/resistance ladders and all-time highs as observed prices (#1060). Thanks @AndyLongest, @daviddaco1, @zzz607, @jay79-boop, @lukiod, @birdxs, and @wiliao.
` that slips through ([#139](https://github.com/HKUDS/Vibe-Trading/issues/139), thanks @sdwxm188). - **2026-05-26** ✅ **Research Goal lifecycle closure**: Goal mode now behaves like a real task runner: Web UI goal creation creates or binds the session and immediately sends the kickoff turn; active goals can be continued, edited, cancelled, and completed across Web/API/CLI/MCP; and the agent advances from the current goal snapshot (criteria, evidence, claims, open items) instead of only the original prompt. Covered-but-still-active goals now enter an audit/status update instead of stopping silently, with regression coverage across backend, CLI, MCP, and frontend events. - **2026-05-25** 🧼 **Cleaner chat UI + composer workflow**: The Web UI keeps chat focused on the next action: upload, swarm, and research-goal modes now live behind the composer `+` menu instead of floating panels. Active context appears above the input as compact chips, and goal details expand inline only when needed. The UI also drops the old custom i18n layer in favor of direct English copy, gates Full Report cards to report-worthy runs, and hardens local dev startup/status reporting for reliable browser smoke tests. - **2026-05-24** 🎯 **Research Goal runtime**: Added a session-scoped Research Goal layer across backend, CLI, API/MCP, SSE, and Web UI. Goals persist claims, acceptance criteria, evidence rows, budgets, and completion policy; agent tools can create goals and attach evidence; `/goal` gives the CLI a direct entry point; REST/MCP expose goal snapshots and evidence writes; SSE keeps chat clients fresh. Follow-up audit fixes locked down verified evidence, blocked live-trading risk tiers through agent tools, wired CLI-created goals into later turns, cleaned goal ledgers on session deletion, enabled replay-all, and fixed cross-session frontend races. - **2026-05-23** 🖥️ **Interactive CLI refresh**: The terminal front door now opens with a larger Vibe-Trading banner, a cleaner prompt divider, prior-turn recap, post-run timing, and a Claude Code-style activity rail for live agent work. Tool calls, web/data fetches, shell-style actions, Markdown answers, and pipe tables render in a more readable transcript, while piped or non-TTY runs keep plain-text output for automation. Generated CLI screenshots are now treated as local artifacts instead of committed docs files, keeping the repository lighter. - **2026-05-22** 🧭 **Swarm recovery + MCP keepalive**: Swarm status now reconciles from live task files on every read, so API/MCP/SSE/list views recover crashed or stale runs instead of showing permanent `running` snapshots. `run_swarm` sends MCP progress heartbeats while it polls, with a fixed first frame of `swarm_started run_id=` for clients that reconnect after transport drops; workers now heartbeat through LLM streaming, grounding fetches, and tool execution. The stale-run reaper uses per-run thresholds and derives terminal status from task states, `SwarmTool` no longer cancels a still-running team just because its wait budget elapsed, and MCP clients can call `reap_stale_runs()` for explicit cleanup. Today's DX pass also refreshed provider default models and aligned CI syntax checks with the new `agent/cli/` package. 22 new regressions cover hydration, terminal recovery, stale reaping, keepalive cadence, env parsing, and heartbeat wiring; the full swarm/MCP suite is at 169 passed, 4 skipped. - **2026-05-21** 🧱 **CLI package refactor**: `agent/cli.py` (3216 LOC) split into the `agent/cli/` package — interactive front door, slash router, Rich components, plus a `_legacy.py` shim that preserves every subcommand and re-exports every public symbol so `cli.cmd_*` / `cli._INIT_ENV_PATH` / `cli.Confirm` keep working. New FastAPI middleware serves the SPA shell when a browser opens `/runs/{id}` or `/correlation` directly; same narrowing landed in the Vite dev proxy. Version unified via `cli/_version.py` (no more drift between `--version` and the banner), `python -m cli` restored via `__main__.py`, and the chat-gate narrowed so `chat --help` / `chat extra` reach legacy argparse instead of being swallowed by the REPL. - **2026-05-20** 🔬 **Hypothesis Registry CLI**: Closes the CLI side of the Hypothesis Registry shipped backend-only on 2026-05-16. `vibe-trading hypothesis list` prints a Rich table or JSON (`--status` filter, `--limit`); `show ` renders a detail panel including linked run cards; `invalidate --note "..."` flips status to `rejected` while preserving prior invalidation notes when `--note` is omitted. Honors the existing `VIBE_TRADING_HYPOTHESES_PATH` env override and adds a per-invocation `--path`. 22 new tests cover wiring, JSON output, status filter, limit, missing-id errors, and note persistence. - **2026-05-19** ✨ **Live tool feedback + graceful cancel**: Long-running tools (backtests, large PDFs, swarm workers) no longer look frozen. Each tool call now emits a 3-second heartbeat plus structured per-stage progress — `run_backtest` shows phase markers (`validate` / `simulate` / `finalize`), `read_document` ticks per page on PDF or per sheet on Excel, `read_url` marks `fetch` / `parse`. The CLI Rich Live dashboard renders a Unicode spinner, ASCII progress bar, ETA, and stacks up to 3 parallel tools keyed by name; the frontend chat ships a new `ToolProgressIndicator` with rAF-coalesced renders, ARIA `role="status"` + hidden native `` for screen readers, and a determinate `ProgressRing` SVG when total is known. First `Ctrl+C` during a CLI run now calls `agent.cancel()` for graceful exit (current step finishes, trace closes cleanly); a second within 2s force-quits. Reusable primitives extracted along the way: `ProgressBar.tsx` and `lib/tools.ts` (shared tool-name i18n). - **2026-05-18** 🧹 **Cleanup pass + three latent bug fixes**: `CompositeEngine` no longer misroutes bare Chinese-futures codes like `RB2410` to `GlobalFuturesEngine` — `_is_china_futures` moved into a shared `_market_hooks` module with a case-normalized product table and a non-CN exchange guard, plus 9 new regression cases. Session FTS5 indexes now persist timestamps so cross-session search can sort by date; the same path also fixed a re-upsert that was wall-clocking every session's `started_at`. The Vite dev-mode proxy gained the missing `/alpha` entry so the AlphaZoo page resolves on `npm run dev`. `tests/test_e2e_harness_v2.py` (real-LLM e2e suite) is now gated behind `VIBE_TRADING_RUN_LIVE_E2E=1` so CI no longer changes shape based on env-key presence. Ruff `per-file-ignores` added for the factor zoo (3783 → 0 F401 noise), frontend tsconfig enables `noUnusedLocals` / `noUnusedParameters` as regression guards, and 76 unused `vw = vwap(...)` boilerplate lines were dropped from `gtja191` alphas. Net **-918 LOC**. - **2026-05-17** 🧬 **Alpha Zoo v1 (0.1.8)**: 452 pre-built quant alphas across 4 zoos — `qlib158` (Microsoft Qlib, Apache-2 attribution), `alpha101` (Kakushadze 101 Formulaic Alphas, paper rewrite from arXiv:1601.00991), `gtja191` (Guotai Junan 2014 short-horizon factor report), and `academic` (Fama-French 5 + Carhart price-based proxies). One-line CLI to bench any zoo on your universe: `vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025`. Ships with AST purity gate, lookahead-guard test, `pytest-socket` network kill-switch, per-zoo LICENSE.md, and a Developer Certificate of Origin (DCO) workflow for community PRs. Auto-rendered Alpha Library at [vibetrading.wiki/alpha-library/](https://vibetrading.wiki/alpha-library/) + research-lab post [Which of the 191 GTJA alphas still work in 2026?](https://vibetrading.wiki/research-lab/posts/alpha-191-in-2026.html). - **2026-05-16** 🧪 **Research spine update**: Added a backend Hypothesis Registry with `create_hypothesis`, `update_hypothesis`, `link_backtest`, and `search_hypotheses`; external-content readers now attach warning-only `security_warnings`; and Shadow Account scanning now uses deterministic OHLCV feature evaluation instead of the old calendar-phase stub. - **2026-05-15** 🪪 The run detail page now surfaces the Trust Layer run card alongside metrics and artifacts, completing the UI side of the `run_card.json` work landed on 2026-05-12. `PersistentMemory.add()` was also hardened on length, empty/whitespace-only names, and C0/C1 control bytes from the #108/#109/#110 triage ([#112](https://github.com/HKUDS/Vibe-Trading/pull/112), thanks @Teerapat-Vatpitak). - **2026-05-14** 🌐 the public wiki is now live at [vibetrading.wiki](https://vibetrading.wiki/) with docs, tutorials, Research Lab, and Alpha Library sections deployed through Cloudflare Pages. Persistent memory is also inspectable from the CLI via `vibe-trading memory list/show/search/forget` ([#102](https://github.com/HKUDS/Vibe-Trading/pull/102), thanks @Teerapat-Vatpitak), and memory tokenization/slugs now support Thai, Arabic, Hebrew, and Cyrillic text ([#104](https://github.com/HKUDS/Vibe-Trading/pull/104)). - **2026-05-13** 🧭 Swarm runs now ground workers with fetched market data and cleaner persisted reports ([#93](https://github.com/HKUDS/Vibe-Trading/pull/93), [#84](https://github.com/HKUDS/Vibe-Trading/pull/84)). - **2026-05-12** 🧾 Backtests now emit `run_card.json` and `run_card.md` alongside artifacts for reproducible research runs. - **2026-05-11** 🧭 **Memory slugs, swarm accounting, and CLI preflight**: Persistent memory now preserves CJK characters when generating file slugs, preventing silent filename collisions for Chinese/Japanese/Korean notes ([#95](https://github.com/HKUDS/Vibe-Trading/pull/95), thanks @voidborne-d). Swarm run totals now prefer provider-reported token usage with the existing estimate fallback ([#94](https://github.com/HKUDS/Vibe-Trading/pull/94), thanks @Teerapat-Vatpitak), and the CLI run UI gained a startup preflight check for common environment issues ([#96](https://github.com/HKUDS/Vibe-Trading/pull/96), thanks @ykykj). - **2026-05-10** 🧱 **Regression guardrails + run metadata**: Memory recall now treats underscores as token boundaries, so snake_case saved memories such as `mcp_wiring_test` match natural-language queries like "mcp wiring" ([#87](https://github.com/HKUDS/Vibe-Trading/pull/87), thanks @hp083625). The MCP server has a subprocess smoke test covering initialize → `tools/list` → `tools/call` to guard the first-call deadlock path ([#86](https://github.com/HKUDS/Vibe-Trading/pull/86)), while low-risk hardening landed for Windows path-sensitive tests, API best-effort exception handling, backtest `run_dir` allowed-root validation, and SwarmRun provider/model metadata ([#88](https://github.com/HKUDS/Vibe-Trading/pull/88), [#90](https://github.com/HKUDS/Vibe-Trading/pull/90), [#91](https://github.com/HKUDS/Vibe-Trading/pull/91), [#92](https://github.com/HKUDS/Vibe-Trading/pull/92), thanks @Teerapat-Vatpitak). - **2026-05-09** 🛡️ **API path hardening + MCP server stability**: API run/session routes now validate path IDs before lookup, rejecting malformed newline-containing parameters and pinning the behavior in the auth/security regression suite ([#80](https://github.com/HKUDS/Vibe-Trading/pull/80), thanks @SJoon99). The MCP server now pre-warms the tool registry on the main thread before serving `tools/call`, avoiding a first-call deadlock in lazy tool discovery ([#85](https://github.com/HKUDS/Vibe-Trading/pull/85), thanks @Teerapat-Vatpitak). The Vite dev proxy also honors `VITE_API_URL` for non-default backend targets ([#82](https://github.com/HKUDS/Vibe-Trading/pull/82), thanks @voidborne-d). - **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](https://github.com/HKUDS/Vibe-Trading/pull/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](https://github.com/HKUDS/Vibe-Trading/pull/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](https://github.com/HKUDS/Vibe-Trading/pull/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](https://github.com/HKUDS/Vibe-Trading/releases/tag/v0.1.7), `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. - **2026-05-05** 🛡️ **Security boundary follow-up**: Completes the remaining security-boundary hardening around explicit CORS origins, Settings credential indicators, web URL reading, and Shadow Account code generation, with regression tests added for each path. Normal localhost CLI/Web UI workflows stay the same; remote deployments should continue using `API_AUTH_KEY` and explicit trusted origins. - **2026-05-04** 🖥️ **Interactive CLI UX + CI cleanup**: Interactive mode now has a live bottom status bar showing provider/model, session duration, last-run latency, and cumulative tool-call stats, plus prompt history navigation and cursor editing with arrow keys via `prompt_toolkit` ([#69](https://github.com/HKUDS/Vibe-Trading/pull/69)). The CLI still falls back to Rich prompts when `prompt_toolkit` or a TTY is unavailable. CI path expectations were also aligned with the hardened file-import sandbox and cross-platform `/tmp` resolution, returning main to green ([`bb67dc7`](https://github.com/HKUDS/Vibe-Trading/commit/bb67dc7cfcc11553c57d8962bee56381dca43758)). - **2026-05-03** 🛡️ **Security hardening patch**: Tightens default API authentication for non-local deployments, protects sensitive run/session/swarm reads, restricts upload and local file-reading boundaries, gates shell-capable tools by entry point, validates generated strategy loading before import, and runs the Docker image as a non-root user with a localhost-only published port by default. Local CLI and localhost Web UI workflows remain low-friction; remote API/Web deployments should set `API_AUTH_KEY`. - **2026-05-02** 🧭 **Dividend analysis + sharper roadmap**: Added the `dividend-analysis` skill for income stocks, payout sustainability, dividend growth, shareholder yield, ex-dividend mechanics, and yield-trap checks, pinned by bundled-skill regression tests. The public roadmap now focuses on upcoming work: Research Autopilot, Data Bridge, Options Lab, Portfolio Studio, Alpha Zoo, Research Delivery, Trust Layer, and Community sharing. - **2026-05-01** 🔥 **Correlation heatmap + OpenAI Codex OAuth + A-share pre-ST filter**: New correlation dashboard/API computes rolling return correlations and renders an ECharts heatmap for portfolio and symbol analysis ([#64](https://github.com/HKUDS/Vibe-Trading/pull/64)). OpenAI Codex provider support now uses ChatGPT OAuth via `vibe-trading provider login openai-codex`, with Settings metadata and adapter regression tests ([#65](https://github.com/HKUDS/Vibe-Trading/pull/65)). Added and hardened the `ashare-pre-st-filter` skill for A-share ST/*ST risk screening, including Sina penalty relevance filtering so securities-account mentions do not inflate E2 counts ([#63](https://github.com/HKUDS/Vibe-Trading/pull/63)). - **2026-04-30** ⚙️ **Web UI Settings + validation CLI hardening**: New Settings page for LLM provider/model, base URL, reasoning effort, and data source credentials, backed by local/auth-protected settings APIs and data-driven provider metadata ([#57](https://github.com/HKUDS/Vibe-Trading/pull/57)). Also hardens `python -m backtest.validation ` so missing, blank, malformed, non-existent, and non-directory inputs fail with clear operator-facing messages before validation starts ([#60](https://github.com/HKUDS/Vibe-Trading/pull/60)). - **2026-04-28** 🚀 **v0.1.6 released** (`pip install -U vibe-trading-ai`): Fixes `vibe-trading --swarm-presets` returning empty after `pip install` / `uv tool install` ([#55](https://github.com/HKUDS/Vibe-Trading/issues/55)) — preset YAMLs now bundled inside the `src.swarm` package and pinned by a 6-test regression suite. Plus AKShare loader correctly routes ETFs (`510300.SH`) and forex (`USDCNH`) to the right endpoints with hardened registry fallback. Rolls up everything since v0.1.5: benchmark comparison panel, `/upload` streaming + size limits, Futu loader (HK + A-share), vnpy export skill, security hardening, frontend lazy loading (688KB → 262KB). - **2026-04-27** 📊 **Benchmark panel + upload safety**: Backtest output now ships a benchmark comparison panel (ticker / benchmark return / excess return / information ratio) with yfinance-backed resolution for SPY, CSI 300, etc. ([#48](https://github.com/HKUDS/Vibe-Trading/issues/48)). Plus `/upload` streams the request body in 1 MB chunks and aborts past `MAX_UPLOAD_SIZE`, bounding memory under oversized/malformed clients ([#53](https://github.com/HKUDS/Vibe-Trading/pull/53)) — pinned by a 4-case regression suite. - **2026-04-22** 🛡️ **Hardening + new integrations**: Path containment enforced in `safe_path` + journal/shadow tool sandbox, `MANIFEST.in` ships `.env.example` / tests / Docker files in sdist, route-level lazy loading shrinks frontend initial bundle 688KB → 262KB. Plus Futu data loader for HK & A-share equities ([#47](https://github.com/HKUDS/Vibe-Trading/pull/47)) and vnpy CtaTemplate export skill ([#46](https://github.com/HKUDS/Vibe-Trading/pull/46)). - **2026-04-21** 🛡️ **Workspace + docs**: Relative `run_dir` normalized to active run dir ([#43](https://github.com/HKUDS/Vibe-Trading/pull/43)). README usage examples ([#45](https://github.com/HKUDS/Vibe-Trading/pull/45)). - **2026-04-20** 🔌 **Reasoning + Swarm**: `reasoning_content` preserved across all `ChatOpenAI` paths — Kimi / DeepSeek / Qwen thinking work end-to-end ([#39](https://github.com/HKUDS/Vibe-Trading/issues/39)). Swarm streaming + clean Ctrl+C ([#42](https://github.com/HKUDS/Vibe-Trading/issues/42)). - **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. - **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.
✨ Key Features
![]() 🔍 Self-Improving Trading Agent
• Natural-language market research
• Strategy drafts and file/web analysis • Memory-backed workflows |
![]() 🐝 Multi-Agent Trading Teams
• Investment, quant, crypto, and risk teams
• Streaming progress and persisted reports • Workers grounded with fetched market data |
![]() 📊 Cross-Market Data & Backtesting
• A / HK / US / Canada / India / Korea equities, crypto, futures, and forex
• Data fallback and composite backtests • PIT data, validation, and run cards |
![]() 👥 Shadow Account
• Broker-journal behavior diagnostics
• Rule-based Shadow Account comparisons • Exportable audit reports and strategy code |
💡 What Is Vibe-Trading?
Vibe-Trading is an open-source research workspace for turning finance questions into runnable analysis. It connects natural-language prompts to market-data loaders, strategy generation, backtest engines, reports, exports, and persistent research memory.
It is designed for research, simulation, and backtesting — and, when you choose, autonomous trading through a broker you authorize yourself (e.g. Robinhood Agentic Trading). It holds no funds and never trades outside the limits you set, and you can halt it instantly.
✨ What You Can Do
| Task | Output |
|---|---|
| Ask a trading question | Market research with tools, data, documents, and reusable session context. |
| Backtest a strategy idea | Strategy code, metrics, benchmark context, validation artifacts, and run cards. |
| Review your own trades | Broker-journal parsing, behavior diagnostics, rule extraction, and Shadow Account comparisons. |
| Read documents & charts | Parse PDF / DOCX / XLSX / PPTX / images with pluggable OCR (read_document), and read chart screenshots semantically with a vision model (analyze_image). |
| Read institutional filings & fund books | SEC 13F manager books with quarter-over-quarter position diffs, ETF constituents across markets, event-contract implied probability, and arXiv / OpenAlex factor extraction — all read-only, on free public sources. |
| Improve repeated research | Persistent memory and editable skills turn useful routines into reusable workflows. |
| Run analyst teams | Multi-agent research reviews for investment, quant, crypto, macro, and risk workflows. |
| Put research into IM channels | Run the same session runtime through WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, and Mochat with CLI, REST, and Web UI controls. |
| Ship usable artifacts | Reports, TradingView Pine Script, TDX, MetaTrader 5, MCP tools, and later research sessions. |
| Bench a pre-built alpha zoo | One-line IC + alive/reversed/dead categorisation across 462 alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + PIT-safe fundamental) on your universe. |
| Spot correlation regimes | An edge-density + hysteresis timeline on the /correlation surface showing when markets fuse into one bloc — descriptive risk context, not a signal. |
⚡ Quick Example
pip install vibe-trading-ai
# Natural-language research
vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024, summarize return and drawdown, then export the report"
# Bench a pre-built alpha zoo (one line)
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20
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"
👥 Shadow Account
Shadow Account starts from your own trading records instead of a generic strategy template.
Upload a broker export, let the agent summarize your behavior, then compare the actual trading path with a rule-based shadow strategy.
| Step | Agent output |
|---|---|
| 1. Read your journal | Parses broker exports from 同花顺, 东方财富, 富途, and generic CSV formats. |
| 2. Profile your behavior | Holding days, win rate, PnL ratio, drawdown, disposition effect, overtrading, momentum chasing, and anchoring checks. |
| 3. Extract your rules | Turns recurring entries/exits into an explicit strategy profile instead of a hand-wavy summary. |
| 4. Run the shadow | Backtests the extracted rules and highlights rule breaks, early exits, missed signals, and alternative trade paths. |
| 5. Deliver the report | Produces an HTML/PDF report that can be inspected, archived, or refined in a later session. |
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"
🧪 Research Workflow
Most runs follow the same evidence path: route the request, load the right market context, execute tools, validate outputs, and keep the artifacts inspectable.
| Layer | What happens |
|---|---|
| Plan | Selects the relevant finance skills, tools, data sources, and swarm preset when useful. |
| Ground | Pulls A-shares, HK/US/Canada equities, crypto, futures, forex, documents, or web context through the available loaders. |
| Execute | Generates testable strategy code, runs tools, and uses the matching backtest engine or analysis workflow. |
| Validate | Adds metrics, benchmark comparison, Monte Carlo, Bootstrap, Walk-Forward, run cards, and warnings where applicable. |
| Deliver | Returns reports, artifacts, tool traces, and exports for TradingView, TDX, MetaTrader 5, MCP clients, or later sessions. |
📡 Data Sources & Smart Fallback
One get_market_data call, 23 free market-data sources (plus the optional QVeris premium marketplace). Set source: "auto" — the loader picks by symbol, then walks a per-market chain ordered by IP-ban risk: never-banned public sources first, throttled / key-gated ones last. Zero config, no single point of failure.
| Source | Markets | Auth | Role |
|---|---|---|---|
tencent · mootdx |
A-share + HK | none | never IP-banned (mootdx = 通达信 TCP) |
eastmoney |
A / US / HK | none | OHLCV + deep fundamentals & flow tools (throttled) |
baostock · akshare |
A (+ US/HK/futures/macro/fx) | none | free fallbacks |
tushare |
A / HK / futures / fund / macro | token | richest A-share |
yahoo |
US / HK / Canada | none | direct chart/quotes/options; TSX .TO / TSXV .V |
sina · stooq |
US | none | K-line to 1984 · EOD CSV |
yfinance |
US / HK / Canada | none | wrapper; TSX .TO / TSXV .V pass through |
longbridge |
US / HK | App Key + App Secret + Access Token | optional historical OHLCV source; install the optional SDK |
finnhub · alphavantage · tiingo · fmp |
US | key | optional providers |
qveris |
global multi-asset | key · credits | premium marketplace — 63+ providers via one key (explicit-only, never in auto fallback) |
okx · ccxt · binance |
crypto | none | OKX + 100+ exchanges + Binance historical / USD-M perps |
futu |
HK / A | OpenD | optional local FutuOpenD |
mt5 |
forex / metals | MT5 terminal | MetaTrader 5 (Exness-style) forex / metal bars, 1m–1D |
tickerall |
forex / metals | key + account (read-only) | same broker MT5 feed, hosted — no local terminal, any OS (explicit-only, never in auto fallback) |
pykrx |
Korea (KRX: KOSPI/KOSDAQ) | none | daily KOSPI / KOSDAQ bars for .KS / .KQ (optional krx extra) |
india_broker |
India (NSE/BSE) | broker login | read-only Shoonya / Dhan bars for .NS / .BO (fallback-chain tail) |
local |
any | none | your own CSV / Parquet / DuckDB via local: prefix |
Fallback chains (by IP-ban risk):
- A-share →
tencent·mootdx·eastmoney·baostock·akshare·tushare·local - US →
yahoo·stooq·sina·eastmoney·yfinance·tiingo·fmp·finnhub·alphavantage·longbridge·akshare·local - HK →
tencent·eastmoney·yahoo·futu·akshare·yfinance·tushare·longbridge·local - India (NSE/BSE) →
yahoo·yfinance·india_broker·local - Korea (KOSPI/KOSDAQ) →
pykrx·yahoo·yfinance·local - Crypto →
okx·ccxt·binance·yfinance·local - Forex / metals →
mt5·yfinance·akshare·local· (futures / fund / macro →tushare/akshare→local)
Using Longbridge explicitly
Longbridge is an optional US/HK historical OHLCV loader. Install its SDK with:
pip install "vibe-trading-ai[longbridge]"
Configure the three credentials in .env:
LONGBRIDGE_APP_KEY=...
LONGBRIDGE_APP_SECRET=...
LONGBRIDGE_ACCESS_TOKEN=...
For a backtest, set source in config.json:
{
"codes": ["QQQ.US"],
"start_date": "2025-01-01",
"end_date": "2025-01-10",
"interval": "1D",
"source": "longbridge"
}
In an Agent conversation, ask explicitly: "Use Longbridge to fetch QQQ.US historical data." The explicit source request is separate from source: "auto"; auto keeps the normal per-market fallback chain.
Beyond OHLCV, 22 read-only data tools reach into fundamentals & flow — fund flow, dragon-tiger, northbound, margin, block trades, shareholder count, lockup, sector, research reports, news, SEC filings, financial statements, options chains, stock profile, market screening, symbol search, macro, iwencai, institutional holdings (13F), ETF look-through, prediction markets, and research papers — all exposed over MCP. An explicit local: symbol never silently falls back to a network source.
💎 Optional premium data — QVeris
![]()
Data: free routing or premium, your choice. Free stays the default: 23 built-in sources with ban-risk fallback, no key, no cost. Premium via QVeris adds 10,000+ capabilities (per QVeris) across 63+ providers for options Greeks, premium fundamentals, China/HK/global data, macro, crypto, news, and filings; failed calls are not charged. Enable it in Settings -> QVeris or vibe-trading data mode paid.
QVeris disclosure: signing up through the Vibe-Trading referral link gets you +1,000 bonus credits and supports the project.
🔩 Detailed Capabilities
Detailed inventories are folded below to keep the main README scannable. Open them when you want to inspect the available building blocks.
Finance Skill Library 89 skills across 9 categories - 📊 89 specialized finance skills organized into 9 categories - 🌐 Complete coverage from traditional markets to crypto & DeFi - 🔬 Comprehensive capabilities spanning data sourcing to quantitative research | Category | Skills | Examples | |----------|--------|----------| | Data Source | 10 | `data-routing`, `tushare`, `yfinance`, `okx-market`, `akshare`, `mootdx`, `ccxt`, `eastmoney`, `sec-edgar`, `qveris` | | Strategy | 19 | `strategy-generate`, `cross-market-strategy`, `technical-basic`, `candlestick`, `ichimoku`, `elliott-wave`, `smc`, `multi-factor`, `ml-strategy` | | Analysis | 23 | `factor-research`, `correlation-regime`, `macro-analysis`, `global-macro`, `valuation-model`, `investor-lenses`, `credit-analysis`, `dividend-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 | 8 | `hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare` | | Tool | 10 | `backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `trade-journal` | | Research | 2 | `alpha-zoo`, `strategy-dev-manager` | | Risk Analysis | 1 | `ashare-pre-st-filter` | Custom Data Source register your own historical OHLCV loader Need a market or vendor we don't ship a loader for? Add your own historical-bar loader and select it with `source=""`. The steps edit package source, so run from a clone (`pip install -e .`). 1. **Write the loader** — create `agent/backtest/loaders/_loader.py` with a class that satisfies `DataLoaderProtocol` (duck-typed, no base class needed) and is tagged with `@register`: ```python import pandas as pd from backtest.loaders.registry import register @register class DataLoader: name = "mysource" # the value you pass as source= markets = {"us_equity"} # a_share/us_equity/hk_equity/crypto/futures/fund/macro/forex requires_auth = False def is_available(self) -> bool: return True # token present? network reachable? def fetch(self, codes, start_date, end_date, *, interval="1D", fields=None): # return {symbol: DataFrame indexed by trade_date, # columns: open, high, low, close, volume} ... ``` 2. **Register the module** so `@register` fires — add `"backtest.loaders._loader"` to `_loader_modules` in `agent/backtest/loaders/registry.py`. 3. **Allow the name** through config validation — add `"mysource"` to `_VALID_SOURCES` in `agent/backtest/runner.py`. 4. *(Optional)* slot it into a market's `FALLBACK_CHAINS` in `registry.py` so `source="auto"` can reach it. 5. **Use it** — `source="mysource"` in a backtest config, or via the CLI / agent. > **Real-time ticks / order-book depth are out of scope for loaders** — the > loader layer is point-in-time historical bars only. Live market data flows > through the broker connectors instead: `okx` / `binance` / `ccxt` for crypto, > `futu` / `tiger` for equities. Broker Connectors 13 brokers — read + paper, bounded-live where supported Connector-first profiles. Most do read + paper-account order placement — IBKR is read-only, Robinhood is live-only (no paper account), and Trading 212 refuses order placement entirely, paper included; live order placement is bounded by a user-defined mandate (symbol allowlist, order-size / exposure caps, daily trade cap, instant kill switch) and never holds funds — the broker executes. Order-placing tools stay off MCP (agent + CLI only). Research / backtest paths are structurally barred from any live endpoint. | Broker | Markets | Capabilities | |--------|---------|--------------| | **IBKR** | global | local TWS / Gateway, read-only | | **Robinhood** | US | Agentic MCP (desktop OAuth) — read + bounded live | | **Tiger** | US / HK / A | read + paper + bounded live | | **Alpaca** | US | read + paper + bounded live (+ TAP credential-isolation mode) | | **OKX** · **Binance** | crypto | read + paper + bounded live | | **Futu** | HK / US / A | read + paper + bounded live | | **eToro** | global | read + paper + bounded live (Public API; demo keys reach only `/demo` paths, plus copy-trading workflows) | | **MetaTrader 5** | forex / CFD | read + paper + bounded live (Exness-style; demo ⇔ paper identity guard) | | **Longbridge** · **Dhan** · **Shoonya** | US / HK · India (NSE/BSE) | read + paper only — no runtime paper/live discriminator, so live order placement is hard-refused | | **Trading 212** | UK / EU | fully read-only — `place_order` / `cancel_order` hard-refuse even paper | Paper-vs-live is a **structural per-broker runtime guard** (account-id format, host separation, demo flag, or trade environment), never a config flag the agent can flip. A broker exposing no such discriminator is capped at paper + read-only. Preset Trading Teams 30 swarm presets - 🏢 30 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. Bring your own: drop preset YAMLs into~/.vibe-trading/swarm/presets/ — they are listed
alongside the bundled roster (same-name files override it, like user skills) and survive upgrades.
Alpha Zoo 462 pre-built quant alphas across 5 families
- 🧬 462 cross-sectional alphas, lookahead-banned at the operator layer
- 📈 IC + IR + alive/reversed/dead categorisation in one CLI command
- 🔬 AST purity gate + 300-row lookahead sentinel test + `pytest-socket` network kill-switch
- 📦 Apache-2 attribution for Qlib; per-zoo `LICENSE.md` declaring formulas as mathematical content
- 🤝 Developer Certificate of Origin (DCO) sign-off workflow for community PRs
| Zoo | Count | Source | License |
|-----|-------|--------|---------|
| **qlib158** | 154 | Microsoft Qlib `Alpha158` (Apache-2.0, commit-pinned) | Apache-2.0 |
| **alpha101** | 101 | Kakushadze (2015), "101 Formulaic Alphas", arXiv:1601.00991 | Formulas are mathematical content |
| **gtja191** | 191 | Guotai Junan (2014), "191 Short-period Trading Alpha Factors" | Formulas are mathematical content |
| **academic** | 12 | Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew + Frazzini-Pedersen betting-against-beta + correlation-rewiring stability (price-based proxies) | Public academic literature |
| **fundamental** | 4 | PIT-safe SEC company facts — earnings yield, ROE, gross profitability, asset growth (filed-date anchored) | Public financial data |
Run `vibe-trading alpha list` to browse, `vibe-trading alpha show ` for formulas + source, `vibe-trading alpha bench --zoo X --universe Y --period Z` to score a whole zoo, and `vibe-trading alpha compare --all` to rank zoos side by side.
Backtest Engines 9 engines + options portfolio, cross-market composite
| Engine | Market | Notes |
|--------|--------|-------|
| **ChinaA** | A-share | T+1, price limits, pre-ST filter |
| **GlobalEquity** | US / HK / Canada | same-session trading; market-specific lots, ticks, and costs |
| **IndiaEquity** | India (NSE/BSE) | T+1, circuit bands, config-driven STT / stamp / SEBI / GST cost stack |
| **KoreaEquity** | Korea (KRX: KOSPI/KOSDAQ) | long-only, ±30% band judged at execution time on the unified tick grid, 2026 0.20% transaction tax |
| **Crypto** | crypto spot / USD-M perps | funding settlements, execution/mark split |
| **ChinaFutures** · **GlobalFutures** | futures | margin, contract multipliers |
| **Forex** | FX / metals | via the `mt5` loader (local terminal) or the hosted `tickerall` loader (no terminal, any OS) |
| **Composite** | cross-market | one shared capital pool across markets (`source="auto"`) |
| **options_portfolio** | options | multi-leg, Greeks, payoff/scenario |
Intraday bars: 1m / 5m / 15m / 30m / 1H / 4H / 1D. 15 metrics + benchmark comparison, **5 portfolio optimizers** (equal-volatility / risk-parity / mean-variance / max-diversification / turnover-aware), and 3 validation tools (Monte Carlo / Bootstrap / Walk-Forward).
Quant Library 265 tested functions across 19 modules, callable from every transport
`src/quantlib` holds one tested implementation of each piece of finance math the
agent needs. Skills **import** these rather than carrying formulas inside
markdown code blocks — if you find a pricing formula living in a `SKILL.md`,
that is a bug, not a pattern.
| Module | What it covers |
|--------|----------------|
| `options` | Black-Scholes price + greeks, implied-volatility inversion |
| `fixedincome` | Bond math, Nelson-Siegel / Svensson curve fitting |
| `credit` | Altman Z-score, Merton / KMV distance-to-default |
| `timeseries` | Stationarity, cointegration, GARCH, bootstrap |
| `risk` · `var_backtest` | VaR / CVaR / EVT and their backtests |
| `attribution` | Brinson-Fachler decomposition |
| `performance` · `fundmath` | TWR / MWR / Modified Dietz; XIRR / MOIC / DPI / TVPI |
| `factormodel` · `eventstudy` | Factor regressions, event studies |
| `multipletesting` · `crossvalidation` | Deflated significance, purged CV |
| `impact` | Market-impact models |
The read-only `quantlib_call` tool reaches all of it through one contract, so the
finance math works on the CLI, the Web UI, the REST API and MCP — including
deployments where `bash` is gated off. It is
structurally not a shell — module allowlist, `__all__`-only dispatch, `export_*`
refused. Econometrics needs the `stats` extra
(`pip install "vibe-trading-ai[stats]"`); those functions lazy-import and tell
you which one is missing.
Valuation & Institutional Research DCF, comps, three-statement, and six research commands
A valuation engine that refuses to invent its own inputs. The one rule in
`contracts.py`: **a missing input makes a model NOT RUNNABLE and is never
silently defaulted** — every default in a valuation model is an opinion wearing
a constant's clothes.
| Model | Behaviour worth knowing |
|-------|-------------------------|
| `run_dcf` | FCFF bridge, WACC build, mid-year discounting, net-debt bridge, WACC×g sensitivity grid. Dual terminal value: each method is cross-checked against the other's implied multiple and implied g |
| `run_comps` | EV bridge, LTM + calendar-year calendarisation, multiple matrix. A peer with a non-positive denominator is **excluded and reported**, never averaged in as a negative multiple |
| `threestatement` | Linked projection with a hard balance assertion, an explicit revolver plug, and an iterated interest↔debt circularity that must converge or raise |
Artifacts are input-hashed and versioned, with xlsx / pptx export.
Six slash commands drive the workflows — `/comps` `/dcf` `/attrib` `/memo`
`/earnings` `/screen` — each carrying a step skeleton and an
arithmetic-consistent worked example (the Brinson decomposition sums exactly to
active return; the earnings bridge sums exactly to the EPS delta). The
`investor-lenses` skill stacks named-investor reasoning frameworks on top as
analysis overlays: each lens is an operating procedure — priority signals,
disqualifying conditions, typical misuse — not a biography, and names no tool.
Beyond bars, `src/entities` ingests irregular dated cash flows (NAVs, capital
calls, coupons) and `cashflow_performance` reports XIRR / MOIC / DPI / TVPI /
TWR / Modified Dietz / MWR over them. This path is deliberately parallel to the
bar engines so a `nav` column can never reach one and get priced as a close.
Governance & Audit Trail answer "what methodology produced that number?"
Every run writes a **manifest** hashing the prompt, the skill contents, the tool
registry and the package versions, so a number produced last month can be traced
to the exact methodology that produced it.
The **audit ledger** chains each record to its predecessor's hash and fsyncs, so
editing or deleting a record is detectable — and an edit that recomputes its own
hash is still caught one record later via `prev_hash_mismatch`. Timestamps are
always caller-supplied; no module here calls `datetime.now()`.
Trace redaction is **sink-aware**: tool-call arguments and the live audit ledger
use a fail-closed sink where `content` stays redacted, while the tool-result
sink releases it and pattern-scrubs its string leaves. `env` is never released
in either.
🎬 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 Start
One-line install (PyPI)
pip install vibe-trading-ai
Then run a first research task:
vibe-trading init
vibe-trading run -p "Backtest a BTC-USDT 20/50 moving-average strategy for 2024 and summarize return and drawdown"
Upgrading from an older version? 0.1.10 moved to LangChain 1.x. If imports break after
pip install -U vibe-trading-aiover a pre-0.1.10 install (e.g. langgraph fails to import), recreate the venv or runpip install --force-reinstall vibe-trading-ai. A fresh install is unaffected.Package name vs commands: The PyPI package is
vibe-trading-ai. Once installed, you get three commands:
Command Purpose vibe-tradingInteractive CLI / TUI vibe-trading serveLaunch FastAPI web server vibe-trading-mcpStart 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
| 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
- OpenAI Codex can also be used with ChatGPT OAuth: set
LANGCHAIN_PROVIDER=openai-codex, then runvibe-trading provider login openai-codex. This does not useOPENAI_API_KEY. - GitHub Copilot can be used with an active Copilot subscription instead of a separately billed LLM API key. See GitHub Copilot SDK provider.
Supported LLM providers: OpenRouter, Requesty, OpenAI, Anthropic (native Messages API), DeepSeek, Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, SiliconFlow (CN + Global), Xiaomi MIMO, Novita AI, iFlytek Spark, Z.ai, NVIDIA NIM, ModelScope, GitHub Copilot, Ollama (local). When no
*_BASE_URLis set, each provider falls back to its canonical endpoint, so just a key is enough. See.env.examplefor config.Tip: All markets work without any API keys thanks to automatic fallback. yfinance/Yahoo (HK/US/Canada), OKX (crypto), mootdx (A-shares, TCP-direct, no IP throttle), and AKShare (A-shares, US, HK, futures, forex) are all free. Tushare token is optional — mootdx is the preferred no-token A-share fallback, with AKShare as a broader backup.
GitHub Copilot SDK provider
The official GitHub Copilot SDK ships as an optional extra, so install it alongside Vibe-Trading with pip install "vibe-trading-ai[copilot]"; installing the Copilot CLI is optional. Authenticate with any one of these supported methods:
gh auth login # use GitHub CLI credentials
# or run `copilot` and sign in # stores credentials in the OS keychain
# or export COPILOT_GITHUB_TOKEN=gho_xxx
Then configure agent/.env:
LANGCHAIN_PROVIDER=copilot
LANGCHAIN_MODEL_NAME=claude-sonnet-5
# COPILOT_GITHUB_TOKEN=gho_xxx # optional; recommended for Docker/CI
Start Vibe-Trading normally. Its preflight reports whether the SDK can authenticate:
vibe-trading
Authentication priority is COPILOT_GITHUB_TOKEN, GH_TOKEN, GITHUB_TOKEN, stored Copilot CLI credentials, then gh credentials. Vibe-Trading does not copy or persist SDK credentials. Host keychain credentials are not automatically available inside Docker, so containers should receive COPILOT_GITHUB_TOKEN.
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.
[!NOTE] OpenAI Codex OAuth with Docker: the browser login needs a terminal so you can paste the callback URL. Run it through Compose, which allocates an interactive terminal automatically:
bash docker compose exec vibe-trading vibe-trading provider login openai-codexIf you use
docker execdirectly, pass-itbefore the container name.
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.
[!NOTE] Using Ollama with Docker: the container reaches a host-side Ollama via
host.docker.internal, notlocalhost(inside the containerlocalhostis the container itself).docker-compose.ymldefaultsOLLAMA_BASE_URLtohttp://host.docker.internal:11434; exportOLLAMA_BASE_URL(or set it in a top-level.env) to point elsewhere. This relies on thehost-gatewaymapping inextra_hosts, which requires Docker Engine ≥ 20.10 / Compose v2 (provided automatically on Docker Desktop).
Your data survives updates: persistent memory, the cross-session search index, user-created skills, shadow accounts, broker connector config, web sessions, backtest runs, swarm history, and uploads all live in named Docker volumes, so git pull && docker compose up --build keeps them. They are deleted only by docker compose down -v.
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.bat # Windows CMD
# .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)[!NOTE] On Windows:
cpis a PowerShell alias forCopy-Item, so the snippets above work as-is in PowerShell. CMD has nocp— usecopy agent\.env.example agent\.envinstead (this applies to the Docker snippet above too). If PowerShell refuses to runActivate.ps1, runSet-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSignedfirst; it applies to that shell session only.
# Terminal 1: API server
vibe-trading serve --port 8899
# Terminal 2: Frontend dev server
cd frontend && npm install && npm run dev # requires Node >= 22.22
Open `http://localhost:5899`. The frontend proxies API calls to `localhost:8899`.
**Production mode (single server):**
cd frontend && npm run build && cd ..
vibe-trading serve --port 8899 # FastAPI serves dist/ as static files
> [!NOTE]
> `vibe-trading serve` binds `0.0.0.0` and is loopback-only by default: opening the UI on the **same machine** (`http://localhost:8899`) works with zero config. If you browse from **another machine, a VM host, or a phone on your LAN**, sensitive endpoints return `403` and the chat shows "Remote API access requires an API key" — set a strong `API_AUTH_KEY` in `agent/.env`, restart, and enter the same key once in **Settings**. (Docker Desktop's host gateway: set `VIBE_TRADING_TRUST_DOCKER_LOOPBACK=1` with the default `127.0.0.1` port bind.)
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:
| Variable | Required | Description |
|---|---|---|
LANGCHAIN_PROVIDER |
Yes | Provider name (openrouter, deepseek, groq, ollama, etc.) |
<PROVIDER>_API_KEY |
Yes* | API key (OPENROUTER_API_KEY, DEEPSEEK_API_KEY, etc.) |
<PROVIDER>_BASE_URL |
Yes | API endpoint URL |
LANGCHAIN_MODEL_NAME |
Yes | Model name (e.g. deepseek-v4-pro) |
LANGCHAIN_REASONING_EFFORT |
No | Reasoning effort (none, low, medium, high, or max) |
LANGCHAIN_USE_RESPONSES_API |
No | Responses transport override: literal true uses /v1/responses when the endpoint supports it; native adapters retain their own transport; all other values use Chat Completions |
TUSHARE_TOKEN |
No | Tushare Pro token for A-share data (falls back to AKShare) |
TIMEOUT_SECONDS |
No | LLM call timeout, default 120s |
API_AUTH_KEY |
Recommended for network deployments | Bearer token required when the API is reachable from non-local clients |
VIBE_TRADING_ENABLE_SHELL_TOOLS |
No | Explicit opt-in for shell-capable tools in remote API/MCP-SSE style deployments |
VIBE_TRADING_ALLOWED_FILE_ROOTS |
No | Extra comma-separated roots for document and broker-journal imports |
VIBE_TRADING_ALLOWED_RUN_ROOTS |
No | Extra comma-separated roots for generated-code run directories |
VIBE_TW_STOCK_DB |
No | Path to a Taiwan-market SQLite snapshot; the read-only taiwan_stock_data tool registers only when it is schema-valid |
VIBE_TRADING_EXTRA_CORS_ORIGINS |
No | Comma-separated origins added to the loopback CORS defaults (CORS_ORIGINS replaces them instead) |
CONTENT_FILTER_WARNING_THRESHOLD |
No | Content-filter warning ratio threshold (default 0.05 = 5%). When the ratio of LLM responses blocked by content moderation exceeds this, the run card warns you to switch providers. |
* Ollama does not require an API key. OpenAI Codex uses ChatGPT OAuth and stores tokens via oauth-cli-kit, not in agent/.env. GitHub Copilot authentication is handled by the official SDK.
Free data (no key needed): A-shares via AKShare, HK/US/Canada equities via Yahoo/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.5-pro, google/gemini-3.5-flash |
Complex swarms (3+ agents), long research sessions, paper-grade analysis |
| Sweet spot (default) | deepseek-v4-pro, deepseek/deepseek-v4-pro, x-ai/grok-4.20, z-ai/glm-5.1, moonshotai/kimi-k2.6, 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 official API + deepseek-v4-pro; OpenRouter users can use deepseek/deepseek-v4-pro.
🖥 CLI Reference
The interactive TUI (vibe-trading) now uses a terminal-native transcript: a startup banner, prompt rule, previous-turn recap, live activity rail, Markdown/table rendering, and run timing all stay in the CLI. Non-interactive invocations such as vibe-trading run, pipes, and --json remain script-friendly.
vibe-trading # interactive TUI
vibe-trading run -p "..." # single run
vibe-trading serve # API server
vibe-trading alpha list # browse 462 pre-built alphas; show / bench / compare / export-manifest sub-commands available
vibe-trading playbook list # five scheduled-research templates; show / create sub-commands available
vibe-trading channels status --local # inspect IM channel config and install hints
vibe-trading provider doctor # print redacted provider/proxy/package diagnostics
Slash commands inside TUI
| Command | Description |
|---------|-------------|
| `/help` | Show keyboard shortcuts and command list |
| `/model` | Switch LLM provider and model |
| `/memory` | Show / manage persistent memory |
| `/history` | Browse and resume prior sessions |
| `/goal` | Start / inspect a finance research goal |
| `/search` | Full-text search across all sessions |
| `/swarm` | Multi-agent presets (committee / quant / risk) |
| `/skill` | List / load / unload skills |
| `/show` | Show prior run by id |
| `/clear` | Clear current conversation |
| `/pine` | Export current strategy as Pine Script |
| `/journal` | Analyze trade journal CSV |
| `/shadow` | Train / view shadow account |
| `/export` | Export current session (md / json) |
| `/debug` | Toggle debug panel (token usage / latency) |
| `/comps` | Comparable company analysis (peer multiples -> implied range) |
| `/dcf` | Discounted cash flow valuation with sensitivity grid |
| `/attrib` | Brinson-Fachler attribution (allocation vs selection) |
| `/memo` | Investment memo — thesis, variant view, scenarios, kill criteria |
| `/earnings` | Earnings review — surprise bridge from revenue to EPS |
| `/screen` | Systematic idea screen — hypothesis, funnel, survivor queue |
| `/playbook` | Scheduled research templates (list / run / schedule) |
| `/connector` | Trading connector profiles (status / start / halt) |
| `/halt` | Kill switch — halt ALL live trading now |
| `/resume` | Clear the kill switch (re-enable live trading) |
| `/data` | Data routing mode |
| `/quit` | Exit (also: q, exit, :q) |
Single run & flags
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
vibe-trading alpha list --zoo gtja191 --limit 10
vibe-trading alpha show gtja191_171
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20
IM channels
IM channel adapters connect outside chat apps to the same session runtime used by the Web UI and CLI. Configure enabled adapters under `channels` in `~/.vibe-trading/agent.json`; SDK-backed adapters are optional extras, and missing SDKs report recovery hints instead of crashing the runtime.
For long-running channel tasks, tune the central assistant-reply wait budget with `replyTimeoutS` (seconds, default `600`):
{
"channels": {
"replyTimeoutS": 1800,
"feishu": {
"enabled": true
}
}
}
This controls how long the shared channel runtime waits for the agent session to produce an assistant message; adapter HTTP/socket timeouts remain adapter-specific.
vibe-trading channels status --local # inspect config and missing SDK hints without API
vibe-trading channels status # query the running API runtime
vibe-trading channels start # start enabled adapters through the API
vibe-trading channels stop # stop enabled adapters through the API
vibe-trading channels login weixin # run an adapter login hook when needed
vibe-trading channels pairing --channel telegram list
The built-in adapters cover `websocket`, `telegram`, `slack`, `discord`, `matrix`, `whatsapp`, `signal`, `qq`, `napcat`, `weixin`, `wecom`, `feishu`, `dingtalk`, `msteams`, `email`, and `mochat`. Use narrow extras such as `pip install "vibe-trading-ai[telegram]"`, or install the full channel set with `pip install "vibe-trading-ai[channels]"`.
**In-chat slash commands** (channel-agnostic, work in all 16 adapters):
| Command | Description |
|---------|-------------|
| `/new` | Reset the current session — the next message starts a fresh conversation |
| `/reset` | Alias for `/new` |
| `/newsession` | Alias for `/new` |
| `/pairing list` | Show pending sender-pairing requests (operators only) |
Commands are case-insensitive and must be sent as the entire message (e.g. `hello /new` is treated as a regular message, not a reset).
> **`/pairing` is operator-gated.** In-chat pairing-control commands are rejected unless the sender is listed as an operator — set `channels.operators` (cross-channel authority) or a channel section's own `operators` list in your channels config. With no operators configured, in-chat `/pairing` is refused (fail-closed) and pairing is managed only through the authenticated CLI (`vibe-trading channels pairing …`) and the auth-gated REST endpoint. This prevents any allow-listed group member from taking over pairing across channels.
💡 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>
Bench a pre-built alpha zoo (one line):
vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20
Browse the catalogue and inspect a single alpha:
vibe-trading alpha list --zoo gtja191 --theme reversal --limit 10
vibe-trading alpha show gtja191_171
Compose a multi-factor signal from the zoo (Python):
from src.skills.multi_factor.zoo_signal_engine import ZooSignalEngine
engine = ZooSignalEngine.from_zoo(["gtja191_171", "gtja191_111", "gtja191_163"])
panel = ... # your wide OHLCV panel
signal = engine.compute_signal(panel)
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
| 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 |
GET |
/alpha/list |
List alphas (filter by zoo/theme/universe) |
GET |
/alpha/{alpha_id} |
Alpha metadata + source code |
POST |
/alpha/bench |
Start a bench job (returns job_id) |
GET |
/alpha/bench/{job_id}/stream |
SSE progress stream |
GET |
/settings/llm |
Read Web UI LLM settings |
PUT |
/settings/llm |
Update local LLM settings |
GET |
/settings/data-sources |
Read local data source settings |
PUT |
/settings/data-sources |
Update local data source settings |
GET |
/channels/status |
Read IM channel runtime and adapter status |
POST |
/channels/start |
Start configured IM channel adapters |
POST |
/channels/stop |
Stop configured IM channel adapters |
POST |
/channels/pairing/command |
Run a sender-pairing command against the shared store |
POST |
/scheduled-runs |
Create a scheduled research job (interval-ms or cron) |
GET |
/scheduled-runs |
List scheduled jobs |
DELETE |
/scheduled-runs/{job_id} |
Cancel a scheduled job |
GET |
/scheduled-runs/playbooks |
List the research templates |
GET |
/scheduled-runs/playbooks/{slug} |
Show one template, with its variables |
POST |
/scheduled-runs/playbooks/{slug} |
Schedule a job from a template |
POST |
/sessions/{id}/cancel |
Stop the session's in-flight run (recorded as cancelled, not failed) |
POST |
/sessions/{id}/title/auto |
Summarize the first exchange into a session title (never overwrites a manual rename) |
GET |
/correlation/regime |
Correlation edge-density regime timeline |
GET |
/agents.json · POST /v1/query |
OpenBB Workspace bridge — registered only with the optional openbb extra; /v1/query requires auth |
Interactive docs are available at http://localhost:8899/docs in keyless
loopback development mode. When API_AUTH_KEY is configured, /docs and
/redoc are disabled; authenticated tooling can fetch /openapi.json with an
Authorization: Bearer <key> header.
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 process tools (bash / background_run / cancel_background) are enabled only for the interactive local CLI. Every other surface — the HTTP/SSE API and the MCP server on all transports (stdio included) — keeps them off unless you explicitly opt in with VIBE_TRADING_ENABLE_SHELL_TOOLS=1 (or pass --enable-shell-tools to vibe-trading-mcp). Transport type never implicitly grants shell access. cancel_background stops only the tracked task ID returned by background_run; broad Python process-name termination is refused because it could terminate Vibe-Trading itself. Document and journal readers are limited to upload/import roots by default; place files under ~/.vibe-trading/uploads, ~/.vibe-trading/runs, ./uploads, ./data (or the legacy agent/uploads / agent/runs), or add a dedicated directory through VIBE_TRADING_ALLOWED_FILE_ROOTS. Sessions, runs, swarm runs, uploads, and the sessions.db index live under ~/.vibe-trading (relocatable via the VIBE_TRADING_HOME shell environment variable); pre-existing history is moved there automatically on first run.
Generated backtest code runs as a local Python subprocess and can make network requests through the configured market-data loaders. Its environment is intentionally narrow: the runner keeps OS/Python basics, proxy/certificate settings, VIBE_TRADING_ALLOWED_RUN_ROOTS, and read-only market-data keys such as TUSHARE_TOKEN, FMP_API_KEY, FRED_API_KEY, and VIBE_TRADING_IWENCAI_KEY. It does not pass LLM provider keys, API auth tokens, shell-tool switches, broker trading secrets, or live/advisory toggles to generated strategy code by default.
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.
The same Settings page includes an IM Channels panel for local operators. It polls /channels/status, shows configured/enabled/available/loaded/running states, surfaces adapter recovery hints, and can start or stop the configured channel runtime without going back to the terminal.
Scheduled research
Run a research prompt or backtest on a repeating schedule — from the Scheduled page in the web UI or over REST. The background executor is off by default — start the server with VIBE_TRADING_ENABLE_SCHEDULER=1 to enable it:
VIBE_TRADING_ENABLE_SCHEDULER=1 vibe-trading serve --port 8899
Then create jobs over REST. schedule is either a bare integer (interval in milliseconds) or a 5-field cron expression (min hour dom mon dow; each field takes *, */n, numbers, comma lists, or low-high ranges like 1-5). Cron runs on the wall clock of the job's optional timezone (an IANA key), so the cadence holds across DST transitions — a spring-forward gap time is skipped, and a fall-back ambiguous time runs once, at its first occurrence. Jobs without a timezone keep plain UTC semantics:
# every 6 hours (cron)
curl -X POST http://localhost:8899/scheduled-runs \
-H "Content-Type: application/json" \
-d '{"prompt":"Scan CSI300 for momentum breakouts and backtest the top 5","schedule":"0 */6 * * *"}'
# weekdays at 23:30 Auckland wall time — DST-proof
curl -X POST http://localhost:8899/scheduled-runs \
-H "Content-Type: application/json" \
-d '{"prompt":"Pre-open scan of NZX names","schedule":"30 23 * * 1-5","timezone":"Pacific/Auckland"}'
# list / cancel
curl http://localhost:8899/scheduled-runs
curl -X DELETE http://localhost:8899/scheduled-runs/<job_id>
Each fire runs the prompt through a fresh agent session (optional backtest parameters go in config), and jobs persist under ~/.vibe-trading/ so they survive restarts. Without the flag, the /scheduled-runs endpoints still record jobs but nothing fires. Add -H "Authorization: Bearer <key>" to each call when API_AUTH_KEY is set.
Five ready-to-schedule templates ship with the scheduler — premarket-brief, earnings-season-tracker, portfolio-checkup, a-share-money-flow, institutional-holdings-diff. Each states the data a run needs in plain language instead of naming tools, so a template keeps working as the tool surface grows, and each is required to name a missing input rather than fill it from memory. Reach them from the CLI, over REST, or with /playbook in the TUI:
vibe-trading playbook list # the five templates
vibe-trading playbook show premarket-brief # body, declared variables, suggested cadence
vibe-trading playbook create premarket-brief \
--var home_market="US equities" --var watchlist="AAPL, MSFT, NVDA" \
--timezone America/New_York
curl http://localhost:8899/scheduled-runs/playbooks
curl http://localhost:8899/scheduled-runs/playbooks/premarket-brief
curl -X POST http://localhost:8899/scheduled-runs/playbooks/premarket-brief \
-H "Content-Type: application/json" \
-d '{"variables":{"home_market":"US equities","watchlist":"AAPL, MSFT, NVDA"}}'
Posting {} schedules a template on its own suggested cadence with its declared defaults. The rendered body becomes the job prompt verbatim, and an undeclared variable is rejected rather than silently ignored.
🔌 MCP Plugin
Vibe-Trading exposes 70 MCP tools for any MCP-compatible client. Runs as a stdio subprocess — no server setup needed. Core research tools work with zero API keys for HK/US/crypto; trading connector tools use the selected connector profile, and run_swarm needs an LLM key.
Environment variables: the client spawns the server itself, so a shell export never reaches it — set them in the client's env block. Generated backtest code is sandboxed to the allowed run roots, so writing results into a workspace of your own needs VIBE_TRADING_ALLOWED_RUN_ROOTS:
{
"mcpServers": {
"vibe-trading": {
"command": "vibe-trading-mcp",
"env": { "VIBE_TRADING_ALLOWED_RUN_ROOTS": "C:\\Users\\me\\research" }
}
}
}
Claude Desktop
Add to `claude_desktop_config.json`:
{
"mcpServers": {
"vibe-trading": {
"command": "vibe-trading-mcp"
}
}
}
OpenClaw
Add to `~/.openclaw/config.yaml`:
skills:
- name: vibe-trading
command: vibe-trading-mcp
For a first research-only smoke test, confirm tool discovery and run a market
data or backtest request before selecting a trading connector profile. Core
research tools can run without broker credentials; connector-backed `trading_*`
tools should be used only after you intentionally select and check a connector
profile. `run_swarm` requires an LLM key.
Cursor / Windsurf / other MCP clients
vibe-trading-mcp # stdio (default)
vibe-trading-mcp --transport http # Streamable HTTP (current MCP spec default) at http://127.0.0.1:8900/mcp
vibe-trading-mcp --transport sse # legacy SSE (deprecated) for older clients
For HTTP clients (QwenPaw, and any client that negotiates by POSTing an
`InitializeRequest`), use `--transport http` and point the client at the single
`/mcp` endpoint — e.g. `http://127.0.0.1:8900/mcp`. Do **not** point an HTTP
client at `/sse`; that path belongs to the deprecated two-endpoint SSE transport
and will return `405 Method Not Allowed` on `POST`. Override the bind address
with `--host` / `--port`.
MCP tools exposed (70): list_skills, load_skill, start_research_goal, get_research_goal, add_goal_evidence, update_research_goal_status, backtest, factor_analysis, alpha_zoo, alpha_bench, analyze_options, analyze_options_payoff, pattern_recognition, read_url, read_document, web_search, write_file, read_file, trading_connections, trading_select_connection, trading_check, trading_account, trading_positions, trading_orders, trading_quote, trading_history, list_swarm_presets, run_swarm, get_market_data, get_fund_flow, get_dragon_tiger, get_northbound_flow, get_margin_trading, get_block_trades, get_shareholder_count, get_lockup_expiry, get_sector_info, get_research_reports, get_stock_news, get_sec_filings, get_financial_statements, get_options_chain, get_stock_profile, screen_market, search_symbol, get_macro_series, iwencai_search, qveris_search, qveris_inspect, qveris_execute, get_institutional_holdings, etf_holdings, prediction_market, research_papers, get_swarm_status, get_run_result, list_runs, reap_stale_runs, retry_run, analyze_trade_journal, extract_shadow_strategy, run_shadow_backtest, render_shadow_report, scan_shadow_signals, quantlib_call, cashflow_performance, orderbook_depth, sentiment, technical_indicators, get_fundamentals.
SWARM external MCP tools
run_swarm workers can call operator-approved tools from external MCP servers. Configure the server-side allowlist in VIBE_TRADING_SWARM_AGENT_CONFIG, ~/.vibe-trading/swarm-agent.json, or the fallback ~/.vibe-trading/agent.json; then list remote tools in a swarm preset using the local MCP wrapper name, such as mcp_internal_kb_search. Caller-provided variables stay template data only and cannot inject MCP URLs, commands, environment variables, or allowlist overrides.
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 89 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:
{
"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 89 skills, enabling auto-fix, auto-improve, and community sharing. Search for Vibe-Trading skills via `search_skills("finance backtest")` in any OpenSpace-connected agent.
MetaTrader 5 (Exness and other MT5 brokers)
Connects to a locally running MT5 terminal through the official MetaTrader5 package (Windows only):
pip install "vibe-trading-ai[mt5]"
Configure ~/.vibe-trading/mt5.json (create it yourself; chmod 600 where supported):
{
"login": 12345678,
"password": "...",
"server": "Exness-MT5Trial8",
"symbol_suffix": "m",
"max_order_volume": 1.0,
"max_order_notional_usd": 10000
}
Then:
vibe-trading connector use mt5-paper-sdk
vibe-trading connector check
vibe-trading connector account
vibe-trading connector quote EURUSD
vibe-trading connector history EURUSD
| Profile | Account | Orders |
|---|---|---|
mt5-paper-sdk |
demo | read-only |
mt5-live-sdk-readonly |
real | read-only |
mt5-paper-trade |
demo | direct placement (connector per-order size guards apply) |
mt5-live-trade |
real | mandate + kill-switch gated |
Safety boundary: "paper" means the broker's own demo account, re-verified on every call — the terminal reports account_info().trade_mode and the logged-in account number, so pointing a paper profile at a real-money account (or the reverse) is refused outright. MT5 sizes orders in lots (1 lot EURUSD = 100,000 EUR); the live mandate gate prices lots through the connector's USD hook, and the connector's own max_order_volume / max_order_notional_usd guards apply on demo as well as live, failing closed when a notional cannot be priced. On hedging accounts (the Exness default), note that an opposing order opens a hedge position — close by ticket instead (pass the position ticket to trading_cancel_order) so the fill is pinned to that position and can only reduce exposure. Rollback / halt path: the kill switch blocks new live orders, while cancellation stays available and is written to the audit log. Mandate limits are denominated in USD; a non-USD account currency is margined by the broker in its own currency.
The mt5 market-data loader — the head of the forex fallback chain — shares this same mt5.json. With no such file it attaches read-only to the most recently used terminal that is already logged in.
🔌 eToro Public API Connector
Connects to eToro's Public API for demo and real accounts via API key pair (x-api-key + x-user-key). Demo and real environments are separated structurally: demo keys only reach /demo API paths.
Configure ~/.vibe-trading/etoro.json (create it yourself; chmod 600 where supported):
{
"api_key": "YOUR_PUBLIC_API_KEY",
"user_key": "YOUR_USER_KEY",
"profile": "paper"
}
Alternatively set ETORO_API_KEY and ETORO_USER_KEY in ~/.vibe-trading/.env.
Then:
vibe-trading connector use etoro-paper-sdk
vibe-trading connector check
vibe-trading connector account
vibe-trading connector positions
vibe-trading connector quote BTC
| Profile | Account | Orders |
|---|---|---|
etoro-paper-sdk |
demo | read-only |
etoro-live-sdk-readonly |
real | read-only |
etoro-paper-trade |
demo | direct placement on demo paths |
etoro-live-trade |
real | mandate + kill-switch gated |
Symbol lookup uses eToro's internalSymbolFull search (e.g. BTC → instrument id 100000). Use the etoro_search_instruments agent tool to resolve tickers before trading.
Safety boundary: demo and real are path-separated and key-bound (paper_guard: path_separated_key_bound). Live risk-increasing actions (open and copy-start/increase) require an authorized mandate, a clear halt state, and a verified USD account for copy-notional enforcement. Validated full and partial position closes, open-order cancellation, and copy close remain available when halted and are audit-logged. Cancelling a pending close or editing position stops is paper-only: the live path fails closed because those operations can increase exposure or transfer extra margin without enough API data to quantify the incremental USD risk. Copy amounts are denominated in the eToro account currency, and every copy start/adjust requires a caller-supplied 1-35 character URL-safe reference id for polling. eToro-specific write tools (etoro_close_position, etoro_copy_*, etc.) are agent tools only — not exposed via MCP or CLI. Rollback: revert the connector commit(s) or disable profiles; halt blocks new live risk-increasing actions.
🔌 Loading Tools from External MCP Servers (MCP Client Mode)
This is the opposite direction from the MCP Plugin above. The MCP Plugin lets other agents call Vibe-Trading tools. This section lets the built-in Vibe-Trading agent call tools from your external MCP servers.
Quick start
Create ~/.vibe-trading/agent.json:
{
"mcpServers": {
"my-server": {
"command": "uvx",
"args": ["my-mcp-server"]
}
}
}
Run any CLI command — tools from ordinary external servers are automatically injected into the agent's registry after local tools:
vibe-trading run "use my-server to do X"
Official IBKR MCP read-only probe
Vibe-Trading can connect directly to Interactive Brokers' official remote MCP
endpoint in read-only mode. Add this to ~/.vibe-trading/agent.json:
{
"mcpServers": {
"ibkr": {
"type": "streamableHttp",
"url": "https://api.ibkr.com/v1/api/mcp",
"auth": {
"type": "oauth",
"scopes": ["mcp.read"],
"clientName": "Vibe-Trading",
"cacheDir": "~/.vibe-trading/live/ibkr/oauth"
},
"enabledTools": ["*"]
}
}
}
Then start the browser OAuth flow:
vibe-trading connector authorize ibkr-live-official-mcp-readonly
The wildcard is accepted only for IBKR's mcp.read probe. Authorizing this
profile confirms access to IBKR's official read scope; generic trading_account
and trading_positions calls stay disabled until IBKR publishes stable read
tool names that Vibe-Trading can map safely. A config that adds mcp.write must
pin an explicit tool allowlist and still passes through the live order guard.
If IBKR issues a pre-registered OAuth client, add clientId and clientSecret
inside auth.
Trading connectors: fastest path
For users who cannot wait for IBKR OAuth client approval, connect to a local
TWS or IB Gateway session. Credentials stay inside IBKR's desktop app; Vibe-
Trading only connects to 127.0.0.1 and exposes it as a connector profile.
Install the optional SDK:
pip install "vibe-trading-ai[ibkr]"
Open TWS paper trading or IB Gateway paper, enable API socket clients, then run:
vibe-trading connector list
vibe-trading connector use ibkr-paper-local
vibe-trading connector configure ibkr-paper-local --yes
vibe-trading connector check
vibe-trading connector account
vibe-trading connector positions
vibe-trading connector orders
vibe-trading connector quote AAPL
vibe-trading connector history AAPL --duration "30 D" --bar-size "1 day"
Default local ports:
| App | Paper | Live read-only |
|---|---|---|
| TWS | 7497 |
7496 |
| IB Gateway | 4002 |
4001 |
The agent exposes connector-scoped tools named trading_connections,
trading_select_connection, trading_check, trading_account,
trading_positions, trading_orders, trading_quote, and trading_history.
Live-broker raw MCP tools are not registered directly as mcp_<broker>_*.
No IBKR order-placement tool is registered.
🔐 TAP Mode — full credential isolation & human-approved writes
Opt-in, off by default. If the TAP_* variables below are unset, the
connector behaves exactly as before (direct broker SDK) — nothing changes.
TAP (Tool Authorization Protocol) is a credential
proxy: the agent never holds the raw broker API secret, and consequential writes
are gated on human approval. With TAP mode on, every Alpaca call — order
placement, cancel, and the reads (account/positions/orders/quote/bars) — is sent
to the TAP proxy's /forward endpoint instead of the broker SDK; TAP injects the
real key server-side, then forwards upstream.
- The agent process holds no Alpaca key at all — and doesn't even need
alpaca-py— because the whole egress goes through TAP. The secret is referenced by name (<CREDENTIAL:alpaca.key_id>) and TAP substitutes it. - Writes block on human approval. An order or cancel cannot reach the broker
without a human approving it; even a prompt-injected "buy now" is held, and
denying it means it never reaches Alpaca. Orders carry a deterministic
client_order_id, so an approval-race retry is deduplicated rather than double-placed. - Reads auto-approve. Account/positions/orders/quote/bars are GETs that TAP forwards without a human step — this is credential isolation (no key in the process), not a gate, so there's ~zero added friction.
allowed_hostson the TAP credential pins where the key may be sent, so a tampered target is rejected (403) before injection.
Enable it:
- In the TAP dashboard, create a multi-secret credential named
alpacaholding your Alpaca key pair as fieldskey_idandsecret_key, assigned to your agent, with allowed hostspaper-api.alpaca.markets(or the live hostapi.alpaca.markets) anddata.alpaca.markets(the market-data host used by quote/bars). Use separate TAP credentials for paper and live (e.g.alpaca-paper/alpaca-live, selected viaTAP_ALPACA_CREDENTIAL), each withallowed_hostspinned to its own API host — TAP then structurally refuses to send the paper key to the live host and vice versa, keeping the paper/live separation crisp end to end. - Add to
agent/.env:
| Variable | Required | Description |
|---|---|---|
TAP_PROXY_URL |
Yes | TAP proxy base URL (e.g. https://proxy.tap.human.tech) |
TAP_AGENT_KEY |
Yes | Your TAP agent API key (secret) |
TAP_ALPACA_CREDENTIAL |
No | TAP credential name for Alpaca (default alpaca) |
TAP_APPROVAL_TIMEOUT |
No | Seconds to wait for a human decision (default 300) |
When a write is placed, approve or deny it in your TAP channel (Telegram / dashboard). An approved order/cancel is forwarded to Alpaca; a denied or timed-out one returns an error and is never sent.
Known limitation — approval race. If the human approves right at the
TAP_APPROVAL_TIMEOUTboundary, TAP may forward the order while the poll has already given up: the gate then reports an error even though the order reached the broker, and themax_trades_per_daycounter under-counts by one. The deterministicclient_order_idkeeps a retry from double-placing that order; if you rely on a tight trades-per-day cap, check open orders after a TAP timeout error before retrying.
Scope: covers Alpaca order placement, cancel, and all five reads — the full connector egress, so the process holds no key on any path. HMAC-signed brokers (Binance/OKX) are follow-ups (client-side signing doesn't fit pure egress injection). The hooks are additive — they live inside the Alpaca connector and leave the live mandate gate unchanged.
Config reference
| Field | Type | Default | Description |
|---|---|---|---|
type |
string | inferred for stdio; required for HTTP | Omit for stdio, or set to sse / streamableHttp for URL-based servers. |
command |
string | required for stdio | Executable to spawn for stdio servers. Invalid for sse / streamableHttp servers. |
args |
array | [] |
Command-line arguments for stdio servers only. |
env |
object | {} |
Extra environment variables merged into the subprocess env for stdio servers only. |
url |
string | required for sse / streamableHttp |
Remote SSE / streamable HTTP endpoint URL. Not used for stdio servers. |
headers |
object | {} |
Extra HTTP headers for sse / streamableHttp servers only. |
toolTimeout |
number | 30 |
Per-tool call timeout in seconds |
initTimeout |
number | unset (max(toolTimeout, 30)) |
MCP initialize / OAuth authorization timeout in seconds. Use this for slow browser authorization without widening ordinary tool calls. |
enabledTools |
array | ["*"] |
Tool allowlist. Use ["*"] to expose all tools from the server |
Config file location: ~/.vibe-trading/agent.json (JSON or YAML).
For URL-based transports, type is required. The agent no longer guesses between SSE and streamable HTTP from the URL suffix.
Per-session overrides (API)
When creating a session via the API you can pass mcpServers inside session.config to extend or override the global config for that session only:
{
"config": {
"mcpServers": {
"research-server": {
"command": "uvx",
"args": ["research-mcp"],
"enabledTools": ["search", "fetch"]
}
}
}
}
Tool naming
Ordinary remote tools are exposed with stable names: mcp_<server>_<tool>.
Live-broker MCP servers stay behind the trading_* connector surface.
If two server names produce the same ASCII-safe local prefix (e.g. foo-bar and foo_bar both become foo_bar), a deterministic hash suffix is appended at the server-segment level so names remain unique. The operator receives a warning:
WARNING: Configured MCP server 'foo-bar' collides with another server after local name
normalization. Using local tool prefix 'mcp_foo_bar_<hash>_<tool>' to keep generated
tool names unique. Rename the server in agent config if you want a different prefix.
v1 limits
| Limit | Detail |
|---|---|
| Transport | stdio, SSE, and streamable HTTP |
| Execution | serial only — MCP tools never enter the parallel readonly path |
| Surfaces | tools only (resources and prompts excluded in v1) |
| Hot reload | not supported — restart the process to pick up config changes |
| Swarm path | MCP tools are not available inside Swarm worker registries in v1 |
📁 Project Structure
Click to expandVibe-Trading/
├── agent/ # Backend (Python)
│ ├── cli/ # CLI package — interactive TUI + subcommands
│ ├── api_server.py # FastAPI server — runs, sessions, upload, swarm, SSE
│ ├── mcp_server.py # MCP server — 70 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 (89 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/ # 94 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, alpha browser + bench, etc.
│ │ │
│ │ ├── factors/ # Alpha Zoo — 462 alphas across 5 families
│ │ │ ├── base.py # 19 operators (rank/scale/ts_*/delta/decay_linear/safe_div/vwap)
│ │ │ ├── registry.py # AST-only metadata load + lazy compute + sanity gates
│ │ │ ├── bench_runner.py # IC + alive/reversed/dead categorisation
│ │ │ └── zoo/ # qlib158 (154) + alpha101 (101) + gtja191 (191) + academic (12) + fundamental (4)
│ │ │
│ │ ├── api/ # FastAPI route modules
│ │ │ └── alpha_routes.py # /alpha/list, /alpha/{id}, /alpha/bench, SSE stream
│ │ │
│ │ ├── skills/ # 89 finance skills in 9 categories (SKILL.md each)
│ │ ├── swarm/ # Swarm DAG execution engine
│ │ │ └── presets/ # 30 swarm preset YAML definitions
│ │ ├── session/ # Multi-turn chat + FTS5 session search
│ │ └── providers/ # LLM provider abstraction
│ │
│ └── backtest/ # Backtest engines
│ ├── engines/ # 8 engines + composite cross-market engine + options_portfolio
│ ├── loaders/ # 24 sources: tushare, okx, binance, yfinance, akshare, baostock, tencent, mootdx, ccxt, futu, pykrx, local, eastmoney, sina, stooq, yahoo, finnhub, alphavantage, tiingo, fmp, longbridge, mt5, qveris, india_broker
│ │ ├── 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, AlphaZoo, RunDetail, Compare, Correlation, Settings
│ ├── components/ # chat, charts, layout
│ └── stores/ # Zustand state management
│
├── Dockerfile # Multi-stage build
├── docker-compose.yml # One-command deploy
├── pyproject.toml # Package config + CLI entrypoint
├── tools/ # Repo-level CI helpers
│ └── ci_grep_gates.sh # rejects yaml.load / trademark / per-stock-data leaks
└── LICENSE # MIT
🏛 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
We ship in phases. Items move to Issues when work begins.
| Phase | Feature | Status |
|---|---|---|
| Trust Layer | Reproducible run cards are emitted and shown in Run Detail; v1 adds tool traces and citations | v0 Shipped |
| Hypothesis Registry | Durable research hypotheses with lifecycle status, data sources, skills, run-card links, and invalidation notes | Backend MVP Shipped |
| Research Autopilot | Manual-first research loop: hypothesis → deterministic backtest → evidence report | Phase 1–3 Shipped |
| Data Bridge | Bring-your-own data: local CSV/Parquet/SQL connectors with schema mapping | Local loader Shipped |
| Options Lab | Vol surface, Greeks dashboard, payoff/scenario explorer | Analytic payoff/scenario tool Shipped; surface/dashboard Planned |
| Portfolio Studio | Risk x-ray, constraints, turnover-aware optimizer, rebalance notes | Turnover-aware optimizer Shipped 0.1.11; rest Planned |
| Alpha Zoo | 462 pre-built alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + academic + fundamental) with one-line bench, agent integration, and Web UI | Shipped 0.1.8, extended through 0.1.12 |
| Strategy Development Manager | Register papers / broker research as factors & strategies with a persistent store + automated IC/Sharpe decay lifecycle | Shipped 0.1.11 |
| Correlation Regime | Edge-density + hysteresis regime timeline layered on /correlation — spot when markets fuse into one bloc |
Shipped 0.1.12 |
| Research Delivery | Scheduled briefs and live research sessions through Slack / Telegram / email-style IM channels | Scheduler + IM Runtime Shipped |
| Community | Shareable skills, presets, and strategy cards | Exploring |
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.13 cycle contributors and credits:
- @santhreal — a 17-PR correctness and resource-leak sweep: the HTTP throttle now sweeps stale buckets interval-aware so rate-limit spacing survives (#1047), the rate limiter stops growing without bound on unique client IPs (#1039), the event bus notifies and removes subscribers on clear (#1046),
_json_loadsis guarded against corrupted JSON in database columns (#1045), NaN/inf volume and close no longer crashformat_grounding_block(#1043),inffrompct_changeon zero equity is replaced (#1041), Shoonya tolerates empty-string numerics (#1038), drawdown is computed from the absolute peak on negative equity (#958) and insolvent empty cross accounts are marked liquidated (#959), plus exact memory index anchors (#956/#957) and an A-share code / trade-journal parsing batch (#919, #926–#935) - @shadowinlife — HK market-data fallback routing repaired with a new Tencent HK source (#1000), Shadow multi-market backtests split per settlement currency (#997), bare US tickers routed to
us_equity(#994), MCP list/dict arguments tolerating JSON-string clients (#993), generated signal engines passing the backtest sandbox validator (#992), and the memory GC dry-run fix (#973) - @honginp — the USD-M perpetual lifecycle end to end: funding and liquidation execution (#903), isolated & cross margin liquidation modelling (#889), ordered fidelity evidence persistence (#936), atomic position rebalancing (#951), and strict historical position rebalancing that preserves collateral, funding, fees and fill evidence (#1019)
- @QCYTSN — the desktop Electron shell lifecycle (#923), Windows packaging with a checksum-pinned embedded runtime and
safeStoragecredential handling (#1015), and Settings model discovery + runtime identity UX (#924) - @Robin1987China — the
technical_indicators(#921) andsentiment(#939) tools, annualisation entries for 15 data sources with a CI coverage gate (#891), indicator inputs read without sampling (#1005), and thequant_strategy_deskfinal report aggregator (#1048) - @Shizoqua — MCP specs cache keyed on remote server identity (#1049), memory FTS5 ranking with importance decay (#1032), swarm detection of
ok/success:falsetool failures (#1028), and lowercase4hresampling in the yfinance loader (#1013) - @ngoanpv — timezone-aware scheduled research (#954, closes #953), one malformed record no longer breaking the whole store (#1003), interval creates without a resolvable zone (#1004), and delete-route job id validation (#980)
- @he-yufeng — risk x-ray artifacts in portfolio runs (#900), Portfolio Studio artifacts surfaced in run detail (#966), yfinance crypto routed to the crypto engine (#970), and hierarchy-routed memory entries keeping their
.mdextension (#984) - @wiliao — Canadian markets end to end: TSX/TSXV market data (#1024) and symbol support through search fail-fast and CSV grounding (#1037)
- @MuggleJinx — session and run history stored under the user runtime root (#925, closes #904) and
~/.vibe-trading/.envloaded on the connector command path (#902, closes #901) - @cgycorey — Alpha Zoo tools reaching MCP (#979) and mapping-shaped Responses stream events accepted (#1034)
- @ofeksh-tr — the eToro Public API connector with path-separated demo/real profiles (#989) — broker connectors 12 → 13
- @su322 — source message ids threaded into IM outbound so QQ replies stay passive (#1008), and the output principle that stops the agent once evidence is sufficient (#1010)
- @zwrong — the
vibe-trading updateself-upgrade command (#1020) - @yrk111222 — ModelScope as an OpenAI-compatible provider (#1011)
- @x-lambda — agent proxy opt-out covering sync and async clients (#995)
- @dineeshd — authenticated API capability surfaces under enforced CSP (#961)
- @hhj123123 — the canonical run root preserved after HOME isolation (#1012)
- @00EVA — the Settings model dropdown auto-resizing so long provider/model slugs stay readable (#1006)
- @darkknight4563 —
bar_returnskept bit-identical for gapped positive series (#895) - @sambazhu — mootdx config pre-seeded in the sandbox home (#982)
- @yagnikpipaliya — self-healing for Claude models that deprecate the
temperaturefield (#890, closes #856) - @JungHoonGhae — the Korea equity (KRX) market engine (#693)
- @shugaoye — the OpenBB Workspace bridge (#817)
- @TSENGCHIENFENG — the read-only Taiwan snapshot tool (#848)
- @ddy4633, @tyj147454413-cmd, @y85998607, @klmtseng, @ebujinovch, @g0rdonL, @AmirF194, @Echoandelementwebsites, @dvirarad, @1anter — correlation, loader, vn.py-export, PIT-fundamentals and alpha-bench fixes carried into this cycle
- @warren618 / Haozhe Wu — the finance-math layer and valuation engine, the entity + cash-flow spine, run manifests and the hash-chained audit ledger, the four read-only data tools, the institutional commands and investor lenses, the grounding-gate repair, the analytic options payoff tool (#946), Codex OAuth recovery (#1014), the Shadow runtime root fix (#1017), release integration and open-PR/issue triage
Disclaimer
Vibe-Trading is research and trading software. It is not investment advice, holds no funds, and runs no execution venue. Trading through a broker channel you explicitly authorize (e.g. Robinhood Agentic Trading) happens only within the limits you set and which you can halt at any time. This broker-trading capability is experimental and not verified by us against a real broker account — use it at your own risk. Past performance does not guarantee future results.
License
MIT License — see LICENSE
⭐ If Vibe-Trading helps your research, a star helps more people find it.
Thanks for visiting Vibe-Trading ✨



