English | 中文 | 日本語 | 한국어 | العربية

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

🔍 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 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

` from clients. > [!NOTE] > **Using Ollama with Docker:** the container reaches a host-side Ollama via `host.docker.internal`, not `localhost` (inside the container `localhost` is the container itself). `docker-compose.yml` defaults `OLLAMA_BASE_URL` to `http://host.docker.internal:11434`; export `OLLAMA_BASE_URL` (or set it in a top-level `.env`) to point elsewhere. This relies on the `host-gateway` mapping in `extra_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 ```bash 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 ``` > [!NOTE] > **On Windows:** `cp` is a PowerShell alias for `Copy-Item`, so the snippets above work as-is in PowerShell. CMD has no `cp` — use `copy agent\.env.example agent\.env` instead (this applies to the Docker snippet above too). If PowerShell refuses to run `Activate.ps1`, run `Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned` first; it applies to that shell session only.

Start web UI (optional)

```bash # 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):** ```bash 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](#-mcp-plugin) section below. ### Path D: ClawHub (one command) ```bash npx clawhub@latest install vibe-trading --force ``` The skill + MCP config is downloaded into your agent's skills directory. See [ClawHub install](#-mcp-plugin) 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.) | | `_API_KEY` | Yes* | API key (`OPENROUTER_API_KEY`, `DEEPSEEK_API_KEY`, etc.) | | `_BASE_URL` | Yes | API endpoint URL | | `LANGCHAIN_MODEL_NAME` | Yes | Model name (e.g. `deepseek-v4-pro`) | | `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 | | `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`.} **Free data (no key needed):** A-shares via AKShare, HK/US equities via yfinance, crypto via OKX, 100+ crypto exchanges via CCXT. The system automatically selects the best available source for each market. ### 🎯 Recommended Models Vibe-Trading is a tool-heavy agent — skills, backtests, memory, and swarms all flow through tool calls. Model choice directly decides whether the agent *uses* its tools or fabricates answers from training data. | 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. ```bash 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 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 all commands | | `/skills` | List all 88 finance skills | | `/swarm` | List 30 swarm team presets | | `/swarm run [vars_json]` | Run a swarm team with live streaming | | `/swarm list` | Swarm run history | | `/swarm show ` | Swarm run details | | `/swarm cancel ` | Cancel a running swarm | | `/list` | Recent runs | | `/show ` | Run details + metrics | | `/code ` | Generated strategy code | | `/pine ` | Export indicators (TradingView + TDX + MT5) | | `/trace ` | Full execution replay | | `/continue ` | Continue a run with new instructions | | `/sessions` | List chat sessions | | `/settings` | Show runtime config | | `/clear` | Clear screen | | `/quit` | Exit |

Single run & flags

```bash 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 ``` ```bash 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 vibe-trading --code vibe-trading --pine # Export indicators (TradingView + TDX + MT5) vibe-trading --trace vibe-trading --continue "refine the strategy" vibe-trading --upload report.pdf ``` ```bash 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`): ```json { "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. ```bash 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 ```bash # 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 ``` **Bench a pre-built alpha zoo** (one line): ```bash vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20 ``` **Browse the catalogue** and inspect a single alpha: ```bash 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): ```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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash 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 | Interactive docs: `http://localhost:8899/docs` ### Security defaults For localhost development, `vibe-trading serve` keeps the browser workflow simple. For any non-local client, sensitive API endpoints require `API_AUTH_KEY`; use `Authorization: Bearer ` 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 `agent/uploads`, `agent/runs`, `./uploads`, `./data`, `~/.vibe-trading/uploads`, or add a dedicated directory through `VIBE_TRADING_ALLOWED_FILE_ROOTS`. 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. The background executor is **off by default** — start the server with `VIBE_TRADING_ENABLE_SCHEDULER=1` to enable it: ```bash 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`): ```bash # 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 * * *"}' # list / cancel curl http://localhost:8899/scheduled-runs curl -X DELETE http://localhost:8899/scheduled-runs/ ``` 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 "` to each call when `API_AUTH_KEY` is set. --- ## 🔌 MCP Plugin Vibe-Trading exposes 54 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.

Claude Desktop

Add to `claude_desktop_config.json`: ```json { "mcpServers": { "vibe-trading": { "command": "vibe-trading-mcp" } } } ```

OpenClaw

Add to `~/.openclaw/config.yaml`: ```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

```bash 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 (54):** `list_skills`, `load_skill`, `start_research_goal`, `get_research_goal`, `add_goal_evidence`, `update_research_goal_status`, `backtest`, `factor_analysis`, `analyze_options`, `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`, `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`. ### 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.

Install from ClawHub (one command)

```bash 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 88 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: ```json { "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 88 skills, enabling auto-fix, auto-improve, and community sharing. Search for Vibe-Trading skills via `search_skills("finance backtest")` in any OpenSpace-connected agent.

--- ## 🔌 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`: ```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: ```bash 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`: ```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: ```bash 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: ```bash pip install "vibe-trading-ai[ibkr]" ``` Open TWS paper trading or IB Gateway paper, enable API socket clients, then run: ```bash 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__*`. 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](https://tap.human.tech) (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 (``) 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_hosts` on the TAP credential pins where the key may be sent, so a tampered target is rejected (403) before injection. **Enable it:** 1. In the TAP dashboard, create a **multi-secret** credential named `alpaca` holding your Alpaca key pair as fields `key_id` and `secret_key`, assigned to your agent, with allowed hosts `paper-api.alpaca.markets` (or the live host `api.alpaca.markets`) **and** `data.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 via `TAP_ALPACA_CREDENTIAL`), each with `allowed_hosts` pinned 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. 2. 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_TIMEOUT` boundary, 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 the `max_trades_per_day` counter under-counts by one. The > deterministic `client_order_id` keeps 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: ```json { "config": { "mcpServers": { "research-server": { "command": "uvx", "args": ["research-mcp"], "enabledTools": ["search", "fetch"] } } } } ``` ### Tool naming Ordinary remote tools are exposed with stable names: `mcp__`. 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__' 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 expand

``` Vibe-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 — 54 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 (88 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/ # 68 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/ # 88 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/ # 7 engines + composite cross-market engine + options_portfolio │ ├── loaders/ # 23 sources: tushare, okx, binance, yfinance, akshare, baostock, tencent, mootdx, ccxt, futu, 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](https://github.com/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](https://github.com/HKUDS/Vibe-Trading/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 | 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](CONTRIBUTING.md) for guidelines. **Good first issues** are tagged with [`good first issue`](https://github.com/HKUDS/Vibe-Trading/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — pick one and get started. Want to contribute something bigger? Check the [Roadmap](#-roadmap) above and open an issue to discuss before starting. --- ## Contributors Thanks to everyone who has contributed to Vibe-Trading! Recent v0.1.12 cycle contributors and credits: - @santhreal — a 30-PR correctness sweep: strict-JSON / finite-number hardening across metrics, factors, pattern, and options (#764/#765/#766/#767/#739/#740/#744), loader correctness (#761 yahoo 1m bars), and session / journal robustness (#762/#763/#768/#769/#770) - @xkam7ar — broad reliability across packaging, web, scheduler, swarm, and CLI (#584), cancellation before the first AgentLoop iteration (#641, closes #638), QVeris session budget + atomic credit accounting (#685/#686), CI / OOS gates (#630/#632), and journal month-filter / side-parse fixes (#626/#628) - @shadowinlife — the Strategy Development Manager skill (#457, closes #455), pluggable OCR + LLM-vision extraction (#548), centralized provider credentials (#563), the 80× signal-alignment vectorization (#698), and swarm MCP-discovery caching (#704) - @ebujinovch — the correlation regime timeline endpoint + UI (#756, closes #719) and its `correlation-regime` skill (#557), plus the `academic_corr_rewire` factor (#705) - @honginp — Binance USD-M routing with execution/mark separation (#470/#716) and the maintenance-bracket decouple that keeps `-PERP` backtests zero-credential (#757) - @StaniellG — the MetaTrader 5 (Exness) broker connector + `mt5` data source (#481) - @tyj147454413-cmd — the Binance fallback loader (#643), bounded OKX history with rate-limit handling (#644), and codex stream-failure classification (#663) - @Marnie0415 — composite sub-engine fallback for unknown symbols (#734) and the frontend `insertBefore` streaming DOM-race fix (#717) - @YZY0108 — the look-ahead-bias fix across all five portfolio optimizers (#487) - @UNHNQ — the SiliconFlow CN + Global providers (#565) - @FenjuFu — the iFlytek Spark provider (#537) - @jelech — the native Anthropic Messages API adapter (#695) - @octo-patch — MiniMax regional API endpoints (#731) - @Thibaultjaigu — the Requesty OpenAI-compatible gateway provider (#474) - @Robin1987China — realized portfolio turnover metrics for every optimizer (#478) - @YogeshModi24 — the Frazzini-Pedersen betting-against-beta academic factor (#480) - @0xZKnw — opt-in TAP mode for Alpaca (#377) - @sambazhu — the fundamental zoo `_VALID_ZOOS` whitelist (#707) - @nareshkps — Robinhood connector `account_number` wiring (#726) - @darkknight4563 — user swarm-presets directory discovery (#570) - @MikeCer — IBKR thread-local connection pool + snapshot quotes (#636) - @Shizoqua — `local` loader interval resampling (#467) - @roberttidball — FastMCP transport import compatibility (#469) - @yxhuang — bare-ticker resolution in the correlation matrix (#472, closes #471) - @Bortlesboat — stale `OPENAI_BASE_URL` provider-switch fix (#484, closes #482) - @ananaymital — preflight `EnvConfig` stale-cache fix (#479, closes #477) - @GabbaTauchi — reported the native zai streaming / base-URL bug (#758) - @warren618 / Haozhe Wu — the correlation regime backend integration, the zai provider streaming + base-URL resolution fix (#758), release integration, and open-PR/issue triage

v0.1.11 cycle contributors

- @shadowinlife — the `api_server` modularization capstone (1,103 → 371 lines, #424 closing #331), centralized env config with the AST CI gate (#440), loader `fetch()` protocol conformance (#437), and the Strategy Development Manager RFC in review (#455/#457) — 12 merged PRs this cycle - @Robin1987China — Research Autopilot Phase 3 loop closure (#267), 4 canonical academic alphas (#277), Shadow Account PIT-safe entry conditions (#302/#314/#316), the turnover-aware portfolio optimizer (#466), scheduled-research route tests (#452), and test-coverage batches for trade-journal / pattern / loader layers (#268/#269/#276) - @muku314115 — first-class Indian equity (NSE/BSE) support: the `IndiaEquityEngine`, cost stack, `.NS`/`.BO` routing, and the `india_broker` bridge (#305) - @mvanhorn — the end-to-end scheduled-research executor (#278), the Trading 212 read-only connector (#321), OpenAI default-model resolution (#319), and Robinhood config validation (#320) - @fei-moss — the `analyze_image` vision tool (#464), NapCat DM pairing (#463), and the IM-media allowed-roots report (#465) - @sambazhu — the value-investing toolkit: financial-rigor + report-audit tools, 4 skills, and the `value_investing_committee` preset (#407/#408) - @Elfsa-Miranda — the evidence-bound alpha research pipeline exploration (#405/#416, since re-scoped into #442) - @Hinotoi-agent — loopback CSRF rejection (#293) and authenticated remote same-origin UI requests (#304) - @dpersek — configurable IM reply timeout (#413) and the provider-preflight redirect fix (#404) - @digger-yu — cross-platform `setup`/`dev` commands (#292) and dev-dependency pre-checks (#349) - @skloxo — tilde expansion + file-roots safety fallback (#299) and reactive zh-CN localization (#301) - @kadaliao — the beginner tutorial (#393) and Alpha Library social cards (#396) - @morluto — CLI resume first-message preservation (#448) and the Codex OAuth default model (#446) - @yxhuang — the Kimi for Coding provider (#435) and the precise #433 diagnosis behind the governance-stack revert - @isaveall — the `validation.json` artifacts-dir fix (#429) and clearer `--swarm-run` errors (#428) - @mustafakamal88 — timezone-aware UTC timestamps (#397) - @irfanallana-oss — the zero-size order guard in `trading_place_order` (#417) - @Shizoqua — the central OHLC-invariant loader guard (#274) - @hobostay — SSRF-guard hardening for CGNAT/mesh ranges + the QQ media redirect fix (#389) - @aeonframework — Pillow / langchain CVE floor bumps (#390) - @hannibal-lee — the pandas version-constraint fix (#329) - @MarkfuGod — dynamic data-source counts + token-gated microcompaction (#296) - @gyx09212214-prog — strict JSON validation outputs (#306) - @LemonCANDY42 — the backtest report library (#224) - @fanfpy — Longbridge Decimal→float serialization (#459) - @asahikiko — packaged SKILL.md capability-count sync + the manifest guard test (#461) - @wison1717-maker — the mandate second-confirmation dialog + unified error toasts (#453) - @imsankz — opencode provider mappings (#444) - @flash1234pku — the tushare reference code-fence fix (#449) - @Penn-Live — the Docker startup route-iteration crash report (#450) - @warren618 / Haozhe Wu — the fundamental factor layer (PIT-safe SEC panels), the QVeris premium track, the IM channel runtime, India-equity integration review, CN search fallbacks, and release integration

v0.1.10 cycle contributors

- @Hinotoi-agent — a security-hardening wave: local-shutdown auth (#241), loopback-host rebinding rejection (#242), agent shell-tool opt-in (#243), settings-write auth (#245), mandate proposal-id containment (#256), persistent-memory type validation (#257), and MCP swarm run-id containment (#258) - @mvanhorn — the opt-in local data cache (#177), Gemini thoughtSignature round-trip over OpenAI-compat tool calls (#176), the custom data loader guide (#194), and the glm/zhipu provider alias + model-name inference (#247) - @gyx09212214-prog — loader robustness for malformed crypto/RSSHub timeout env vars (#227, #240), requested yfinance end-date inclusion (#226), strict run-card JSON for non-finite metrics (#238), and ddgs retry-fallback coverage (#239) - @BillDin — swarm agent status in the chat UI (#188), explicit preset-name handling (#189), the loader-backed market-data tool for swarm workers (#199), and preset-context continuations (#200) - @Robin1987China — the Research Autopilot goal-hypothesis bridge (#260), the local CSV/Parquet/DuckDB data loader (#252), and an assistant-prefill fix + configurable Kimi User-Agent (#248) - @LemonCANDY42 — the read-only runtime status dashboard (#210), persisted AgentLoop usage artifacts (#223), and opt-in Run Detail chart payloads (#225) - @zwrong — the trace.jsonl overhaul with zero truncation + offload (#206) and session-id on exit + `resume ` (#218) - @forge-builder — the AI contributor guide (#173) and the OpenClaw MCP research-only smoke-test docs (#165) - @skloxo — Chinese (zh-CN) frontend localization (adopted from #217) - @LeeCQiang — Chinese docstrings across all 452 Alpha Zoo factors (#180) - @KaiLuettmann — GHCR pre-built image publishing on release (#187) - @ngoanpv — Gemini thought_signature preservation through the AgentLoop dict path (#184) - @ShahNewazKhan — Docker host-Ollama reachability via host.docker.internal (#196) - @sambazhu — frontend sync of completed chat attempts (#236) - @bhlt — baostock-native code format support (#230) - @octo-patch — MiniMax M3 default model upgrade (#162) - @warren618 / Haozhe Wu — the global data layer (8 sources + 18 read-only data tools), the 10 broker SDK connectors, the alpha-compare full stack, the provider-reliability overhaul, multi-engine web_search fallback, responsive Stop + SSE reconnect, and release integration

--- ## 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](LICENSE) ---

⭐ If Vibe-Trading helps your research, a star helps more people find it.

---

Thanks for visiting Vibe-Trading ✨