AthenaOS

The AI Portfolio Intelligence Platform

One workspace for portfolio intelligence, market research, AI agents, financial data,
news, technical analysis, watchlists, backtesting, and conversational AI.

Website · Docs · Highlights · Features · Quick Start · Examples · API / MCP · Roadmap · Contributing

Placeholder links: athenaos.ai, the GitHub org athenaos/athenaos, and the Discord invite below are placeholders for this rebrand pass — swap in real URLs before publishing. See the modification checklist delivered alongside this rewrite.

💡 What Is AthenaOS?

AthenaOS is an AI-native investment operating system. Instead of switching between a charting app, a news terminal, a spreadsheet, a backtester, and a chat window, AthenaOS puts all of it behind one conversational agent: portfolio intelligence, market research, financial data, news, technical analysis, watchlists, backtesting, and a library of AI agents that can research, debate, and act on your behalf — all in one platform, accessible from natural language.

Today, AthenaOS ships as an open-core engine you can run yourself (CLI, self-hosted API + Web UI, Docker, or as an MCP tool server for other agents). A managed, multi-tenant AthenaOS Cloud is on the roadmap — see Roadmap.

It is built for research, simulation, and backtesting — and, when you choose, autonomous trading through a broker you authorize yourself. It holds no funds, never trades outside the limits you set, and you can halt it instantly.

✨ Product Highlights

AthenaOS's engine has grown from a single-agent research CLI into a full portfolio-intelligence stack:

Portfolio & trading intelligence — a connector-first trading layer spans 10+ brokers (IBKR, Robinhood, Tiger, Alpaca, OKX, Binance, Futu, Dhan, Shoonya, Trading 212, Longbridge) with a unified read-only account/positions/orders/quote/history surface, plus bounded, mandate-gated paper and live order placement behind a kill switch and audit ledger.
Conversational delivery everywhere — the same session runtime now reaches users through 16 channel adapters (WebSocket, Telegram, Slack, Discord, Matrix, WhatsApp, Signal, QQ/NapCat, WeChat/WeCom, Feishu/Lark, DingTalk, Teams, email, Mochat), not just the CLI or Web UI.
Alpha Zoo — 456 pre-built, cross-sectional quant factors across four zoos (Qlib158, Kakushadze 101, GTJA 191, an academic family), each benchable in one command with IC/IR and alive/reversed/dead categorisation.
Global data layer — 18 market-data sources across A-share, HK, US, crypto, futures, and forex, with automatic IP-ban-risk-ordered fallback and zero required API keys for most markets.
Research Autopilot & Hypothesis Registry — durable, auditable research: a hypothesis → signal engine → backtest loop with lifecycle status, evidence, and invalidation notes.
Shadow Account — turns a broker trade-history export into a rule-based strategy profile, then backtests it against your actual trades to surface disposition effect, overtrading, and missed signals.
Trust Layer — every backtest emits a reproducible run card (metrics, artifacts, tool trace) so results are inspectable and auditable after the fact.
Security-hardened by default — fail-closed order gates, mandate enforcement, path-containment sandboxing, CSRF-hardened local API, and an AST purity/lookahead gate protecting every quant factor.

Full version history lives in CHANGELOG.md.

✨ Key Features

🔍 Portfolio Intelligence Agent • Natural-language market research • Strategy drafts and file/web analysis • Memory-backed workflows across sessions	🐝 Multi-Agent Research 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

✨ What You Can Do

Task	Output
Ask a portfolio or market question	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.
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 chat 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 456 alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + FF5 + Carhart) on your universe.

⚡ Quick Example

pip install -e .

# Natural-language research
athenaos 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)
athenaos alpha bench --zoo gtja191 --universe csi300 --period 2018-2025 --top 20

athenaos --upload trades_export.csv
athenaos 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.

athenaos --upload trades_export.csv
athenaos 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 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, 18 market-data sources. 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	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 / futures / fund / macro	token	richest A-share
`yahoo` · `sina` · `stooq`	US (/HK)	none	direct chart/quotes/options · K-line to 1984 · EOD CSV
`yfinance`	US / HK	none	wrapper
`finnhub` · `alphavantage` · `tiingo` · `fmp`	US	key	optional providers
`okx` · `ccxt`	crypto	none	OKX + 100+ exchanges
`futu`	HK / A	OpenD	optional local FutuOpenD
`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 · akshare · local
HK → eastmoney · yahoo · futu · yfinance · akshare · local
Crypto → okx · ccxt · yfinance · local · (futures / fund / macro / forex → tushare/akshare → local)

Beyond OHLCV, 18 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, institutional holdings, market screening, symbol search, and macro — all exposed over MCP. An explicit local: symbol never silently falls back to a network source.

🔩 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 _{79 skills across 8 categories}

📊 79 specialized finance skills organized into 8 categories
🌐 Complete coverage from traditional markets to crypto & DeFi
🔬 Comprehensive capabilities spanning data sourcing to quantitative research

Category	Skills	Examples
Data Source	9	`data-routing`, `tushare`, `yfinance`, `okx-market`, `akshare`, `mootdx`, `ccxt`, `eastmoney`, `sec-edgar`
Strategy	17	`strategy-generate`, `cross-market-strategy`, `technical-basic`, `candlestick`, `ichimoku`, `elliott-wave`, `smc`, `multi-factor`, `ml-strategy`
Analysis	17	`factor-research`, `macro-analysis`, `global-macro`, `valuation-model`, `earnings-forecast`, `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	7	`hk-connect-flow`, `us-etf-flow`, `edgar-sec-filings`, `financial-statement`, `adr-hshare`
Tool	11	`backtest-diagnose`, `report-generate`, `pine-script`, `doc-reader`, `web-reader`, `vnpy-export`, `alpha-zoo`
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="<name>". The steps edit package source, so run from a clone (pip install -e .).

Write the loader — create agent/backtest/loaders/<name>_loader.py with a class that satisfies DataLoaderProtocol (duck-typed, no base class needed) and is tagged with @register:

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}
        ...

Register the module so @register fires — add "backtest.loaders.<name>_loader" to _loader_modules in agent/backtest/loaders/registry.py.
Allow the name through config validation — add "mysource" to _VALID_SOURCES in agent/backtest/runner.py.
(Optional) slot it into a market's FALLBACK_CHAINS in registry.py so source="auto" can reach it.
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.

Preset Trading Teams _{29 swarm presets}

🏢 29 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 athenaos --swarm-presets to explore all.}

Alpha Zoo _{456 pre-built quant alphas across 4 zoos}

🧬 456 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	10	Fama-French 5 + Carhart momentum + Jegadeesh reversal + George-Hwang 52-week-high + Amihud illiquidity + Harvey-Siddique skew (price-based proxies)	Public academic literature

Run athenaos alpha list to browse, athenaos alpha show <id> for formulas + source, athenaos alpha bench --zoo X --universe Y --period Z to score a whole zoo.

🎬 Demo

Placeholder: the original demo recordings show the prior brand's UI. Two engine walkthroughs are still bundled locally at assets/Frontend.mp4 (Web UI) and assets/cli.mp4 (CLI) pending a re-record under AthenaOS branding.

🚀 Quick Start

AthenaOS has two on-ramps today: self-host the open-core engine (this repo), or join the AthenaOS Cloud waitlist for the managed multi-tenant version. This section covers the self-hosted engine.

One-line install (source)

git clone https://github.com/athenaos/athenaos.git
cd athenaos
pip install -e .

Then run a first research task:

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

Command names: installing from this source tree registers two equivalent CLI names — athenaos (new) and vibe-trading (legacy alias, kept for compatibility with the underlying open-source engine this platform is built on). Use whichever you prefer; both point at the same binary. The historical PyPI package name is vibe-trading-ai; a rename to athenaos on PyPI is pending.

Command Purpose

athenaos Interactive CLI / TUI

athenaos serve Launch FastAPI web server

athenaos-mcp Start MCP server (for Claude Desktop, OpenClaw, Cursor, etc.)

athenaos init              # interactive .env setup
athenaos                   # launch CLI
athenaos serve --port 8899 # launch web UI
athenaos-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

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 run athenaos provider login openai-codex. This does not use OPENAI_API_KEY.

Supported LLM providers: OpenRouter, OpenAI, DeepSeek, Gemini, Groq, DashScope/Qwen, Zhipu, Moonshot/Kimi, MiniMax, Xiaomi MIMO, Z.ai, Ollama (local). See .env.example for config.

Tip: All markets work without any API keys thanks to automatic fallback. yfinance (HK/US), 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.

Path A: Docker (zero setup)

git clone https://github.com/athenaos/athenaos.git
cd athenaos
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.

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

git clone https://github.com/athenaos/athenaos.git
cd athenaos
python -m venv .venv

# Activate
source .venv/bin/activate          # Linux / macOS
# .venv\Scripts\Activate.ps1       # Windows PowerShell

pip install -e .
cp agent/.env.example agent/.env   # Edit — set your LLM provider API key
athenaos                           # Launch interactive TUI

Start web UI (optional)

# Terminal 1: API server
athenaos serve --port 8899

# Terminal 2: Frontend dev server
cd frontend && npm install && npm run dev

Open http://localhost:5899. The frontend proxies API calls to localhost:8899.

Production mode (single server):

cd frontend && npm run build && cd ..
athenaos serve --port 8899     # FastAPI serves dist/ as static files

[!NOTE] athenaos 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.

🧠 Environment Variables

Copy agent/.env.example to agent/.env and uncomment the provider block you want. Each provider needs 3-4 variables.

Naming note: the engine's environment variables and local config directory (~/.vibe-trading/) still use their original VIBE_TRADING_* prefix inherited from the open-source engine this platform builds on. Renaming these touches many source files and would be a code change, not a documentation change, so it's tracked as a follow-up (see Roadmap) rather than done silently in this pass.

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`)
`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

AthenaOS 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 (athenaos) 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 athenaos run, pipes, and --json remain script-friendly.

athenaos               # interactive TUI
athenaos run -p "..."  # single run
athenaos serve         # API server
athenaos alpha list    # browse 456 pre-built alphas; show / bench / compare / export-manifest sub-commands available
athenaos channels status --local  # inspect IM channel config and install hints
athenaos provider doctor  # print redacted provider/proxy/package diagnostics

Slash commands inside TUI

Command	Description
`/help`	Show all commands
`/skills`	List all 79 finance skills
`/swarm`	List 29 swarm team presets
`/swarm run <preset> [vars_json]`	Run a swarm team with live streaming
`/swarm list`	Swarm run history
`/swarm show <run_id>`	Swarm run details
`/swarm cancel <run_id>`	Cancel a running swarm
`/list`	Recent runs
`/show <run_id>`	Run details + metrics
`/code <run_id>`	Generated strategy code
`/pine <run_id>`	Export indicators (TradingView + TDX + MT5)
`/trace <run_id>`	Full execution replay
`/continue <run_id> <prompt>`	Continue a run with new instructions
`/sessions`	List chat sessions
`/settings`	Show runtime config
`/clear`	Clear screen
`/quit`	Exit

Single run & flags

athenaos run -p "Backtest BTC-USDT MACD strategy, last 30 days"
athenaos run -p "Analyze AAPL momentum" --json
athenaos run -f strategy.txt
echo "Backtest 000001.SZ RSI" | athenaos run

athenaos -p "your prompt"
athenaos --skills
athenaos --swarm-presets
athenaos --swarm-run investment_committee '{"topic":"BTC outlook"}'
athenaos --list
athenaos --show <run_id>
athenaos --code <run_id>
athenaos --pine <run_id>           # Export indicators (TradingView + TDX + MT5)
athenaos --trace <run_id>
athenaos --continue <run_id> "refine the strategy"
athenaos --upload report.pdf

athenaos alpha list --zoo gtja191 --limit 10
athenaos alpha show gtja191_171
athenaos 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.

athenaos channels status --local   # inspect config and missing SDK hints without API
athenaos channels status           # query the running API runtime
athenaos channels start            # start enabled adapters through the API
athenaos channels stop             # stop enabled adapters through the API
athenaos channels login weixin     # run an adapter login hook when needed
athenaos 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]".

💡 Examples

Strategy & Backtesting

# Moving average crossover on US equities
athenaos 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
athenaos 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
athenaos 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
athenaos --pine <run_id>

Bench a pre-built alpha zoo (one line):

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

Browse the catalogue and inspect a single alpha:

athenaos alpha list --zoo gtja191 --theme reversal --limit 10
athenaos 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
athenaos run -p "Research NVDA: earnings trend, analyst consensus, option flow, and key risks for next quarter"

# Macro analysis
athenaos run -p "Analyze the current Fed rate path, USD strength, and impact on EM equities and gold"

# Crypto on-chain
athenaos run -p "Deep dive BTC on-chain: whale flows, exchange balances, miner activity, and funding rates"

Swarm Workflows

# Bull/bear debate on a stock
athenaos --swarm-run investment_committee '{"topic": "Is TSLA a buy at current levels?"}'

# Quant strategy from screening to backtest
athenaos --swarm-run quant_strategy_desk '{"universe": "S&P 500", "horizon": "3 months"}'

# Crypto desk: funding + liquidation + flow → risk manager
athenaos --swarm-run crypto_trading_desk '{"asset": "ETH-USDT", "timeframe": "1w"}'

# Global macro portfolio allocation
athenaos --swarm-run macro_rates_fx_desk '{"focus": "Fed pivot impact on EM bonds"}'

Cross-Session Memory

# Save your preferences once
athenaos run -p "Remember: I prefer RSI-based strategies, max 10% drawdown, hold period 5–20 days"

# The agent recalls them in future sessions automatically
athenaos run -p "Build a crypto strategy that fits my risk profile"

Upload & Analyze Documents

# Analyze a broker export or earnings report
athenaos --upload trades_export.csv
athenaos run -p "Profile my trading behavior and identify any biases"

athenaos --upload NVDA_Q1_earnings.pdf
athenaos run -p "Summarize the key risks and beats/misses from this earnings report"

🌐 API Server

athenaos 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, athenaos 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 tools are available to local CLI and trusted localhost workflows, but are not exposed to remote API sessions unless you explicitly set VIBE_TRADING_ENABLE_SHELL_TOOLS=1. 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 ~/.vibe-trading/imports, or add a dedicated directory through VIBE_TRADING_ALLOWED_FILE_ROOTS.

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:

VIBE_TRADING_ENABLE_SCHEDULER=1 athenaos 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):

# 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/<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.

🔌 MCP Plugin

AthenaOS 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:

{
  "mcpServers": {
    "athenaos": {
      "command": "athenaos-mcp"
    }
  }
}

OpenClaw

Add to ~/.openclaw/config.yaml:

skills:
  - name: athenaos
    command: athenaos-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

athenaos-mcp                  # stdio (default)
athenaos-mcp --transport sse  # SSE for web clients

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.

🔌 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 AthenaOS tools. This section lets the built-in AthenaOS 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:

athenaos run "use my-server to do X"

Official IBKR MCP read-only probe

AthenaOS 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": "AthenaOS",
        "cacheDir": "~/.vibe-trading/live/ibkr/oauth"
      },
      "enabledTools": ["*"]
    }
  }
}

Then start the browser OAuth flow:

athenaos 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 AthenaOS 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; AthenaOS 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:

athenaos connector list
athenaos connector use ibkr-paper-local
athenaos connector configure ibkr-paper-local --yes
athenaos connector check
athenaos connector account
athenaos connector positions
athenaos connector orders
athenaos connector quote AAPL
athenaos 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.

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 expand

athenaos/
├── 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 (79 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 — 456 alphas across 4 zoos
│   │   │   ├── 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 (10)
│   │   │
│   │   ├── api/                    # FastAPI route modules
│   │   │   └── alpha_routes.py     #   /alpha/list, /alpha/{id}, /alpha/bench, SSE stream
│   │   │
│   │   ├── skills/                 # 79 finance skills in 8 categories (SKILL.md each)
│   │   ├── swarm/                  # Swarm DAG execution engine
│   │   │   └── presets/            #   29 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/                #   18 sources: tushare, okx, yfinance, akshare, baostock, tencent, mootdx, ccxt, futu, local, eastmoney, sina, stooq, yahoo, finnhub, alphavantage, tiingo, fmp
│       │   ├── 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

🗺 Roadmap

Items move to Issues when work begins.

Phase	Feature	Status
AthenaOS Cloud	Managed, multi-tenant SaaS: hosted workspaces, org/team accounts, SSO, usage-based billing	Planned
Portfolio Studio	Risk x-ray, constraints, turnover-aware optimizer, rebalance notes, unified watchlists	Planned
Options Lab	Vol surface, Greeks dashboard, payoff/scenario explorer	Planned
Trust Layer	Reproducible run cards with tool traces and citations	v0 Shipped, v1 in progress
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
Alpha Zoo	456 pre-built alphas (Qlib 158 + Kakushadze 101 + GTJA 191 + FF5 + Carhart) with one-line bench, agent integration, and Web UI	Shipped
Research Delivery	Scheduled briefs and live research sessions through Slack / Telegram / email-style IM channels	Scheduler + IM Runtime Shipped
Environment/config rename	Migrate `VIBE_TRADING_` env vars and `~/.vibe-trading/` config path to `ATHENAOS_` / `~/.athenaos/` with a compatibility shim	Planned
Community	Shareable skills, presets, and strategy cards in a marketplace	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.

Acknowledgments

AthenaOS's open-core engine builds on Vibe-Trading, an open-source finance research agent, and the work of its contributors. The original MIT license and copyright notice are preserved in LICENSE unchanged, and per-zoo attribution for third-party research (Qlib, Kakushadze, GTJA, academic factor models) is preserved in each zoo's own LICENSE.md under agent/src/factors/zoo/.

Disclaimer

AthenaOS 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 happens only within the limits you set and which you can halt at any time. 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 AthenaOS helps your research, a star helps more people find it.

Name		Name	Last commit message	Last commit date
.devcontainer		.devcontainer
.github		.github
agent		agent
assets		assets
docs		docs
frontend		frontend
plans		plans
scripts		scripts
tools		tools
wiki		wiki
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Memory.md		Memory.md
README.md		README.md
docker-compose.yml		docker-compose.yml
pyproject.toml		pyproject.toml
start.ps1		start.ps1
start.sh		start.sh
stop.ps1		stop.ps1
stop.sh		stop.sh

Command	Purpose
`athenaos`	Interactive CLI / TUI
`athenaos serve`	Launch FastAPI web server
`athenaos-mcp`	Start MCP server (for Claude Desktop, OpenClaw, Cursor, etc.)

Latest commit

History

Folders and files

Repository files navigation

AthenaOS

💡 What Is AthenaOS?

✨ Product Highlights

✨ Key Features

🔍 Portfolio Intelligence Agent

🐝 Multi-Agent Research Teams

📊 Cross-Market Data & Backtesting

👥 Shadow Account

✨ What You Can Do

⚡ Quick Example

👥 Shadow Account

🧪 Research Workflow

📡 Data Sources & Smart Fallback

🔩 Detailed Capabilities

🎬 Demo

🚀 Quick Start

One-line install (source)

Or choose a path

Prerequisites

Path A: Docker (zero setup)

Path B: Local install

Path C: MCP plugin

🧠 Environment Variables

🎯 Recommended Models

🖥 CLI Reference

💡 Examples

Strategy & Backtesting

Market Research

Swarm Workflows

Cross-Session Memory

Upload & Analyze Documents

🌐 API Server

Security defaults

Web UI Settings

Scheduled research

🔌 MCP Plugin

SWARM external MCP tools

🔌 Loading Tools from External MCP Servers (MCP Client Mode)

Quick start

Official IBKR MCP read-only probe

Trading connectors: fastest path

Config reference

Per-session overrides (API)

Tool naming

v1 limits

📁 Project Structure

🗺 Roadmap

Contributing

Acknowledgments

Disclaimer

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages