📈 Risk-Aware Trading Agents

AI trading agents for US stocks that check the macro calendar, the fear index and verified news before they buy

Buy when others are afraid · keep 30% in cash · never panic-sell

📊 2026 backtest with news: +15.9% vs SPY +12.1% · max drawdown -5.3% vs -8.9% · Sharpe 1.70 vs 0.77 · details

🔬 News backtesting without look-ahead bias: a point-in-time 2026 dataset (prices, VIX, 16,945 headlines and SEC filings) ships with the package, every run gets a look-ahead check, and LLM trading agents can be tested step by step over MCP · research kit

中文说明 → README_zh.md · Website · What's new · Screenshots · Quick start · Paper agents · MCP · Strategy lab · Strategy library · Brokers · Changelog

pip install "risk-aware-trading-agents[dashboard,mcp] @ git+https://github.com/jackson-cmd/risk-aware-trading-agents"
riskaware dashboard          # the web UI on http://localhost:8501, English and 中文

Contents

• 🆕 What's new · 📸 Screenshots · 💡 The idea · ✨ Highlights · 🚀 Quick start
• 🤖 Paper-trading agents · 🔗 MCP server · 🧪 Strategy lab · 🔬 Research kit
• 🧠 How it works: Market regimes · Risk profiles
• 📊 Backtest: News in backtests · 📚 Strategy library: Options · 🧩 Write your own strategy
• 🔌 Brokers · 🔒 Safety · 🔧 Configuration · 💻 CLI · 📁 Project layout
• ❓ FAQ · 🧭 Roadmap · 🤝 Contributing · ❗ Disclaimer · 📝 Citation · 📜 License

🆕 What's new

• 0.7.1 · 🐳 Docker image and Codespaces: run the dashboard or the MCP server from ghcr.io/jackson-cmd/risk-aware-trading-agents without installing Python, or open the repository in GitHub Codespaces with everything installed. How →
• 0.7.0 · 🔬 A frozen 2026 market for research: point-in-time prices, VIX and news for the whole year ship with the package. Ask what was known at any close, let Claude turn a strategy you describe into code and test it, or let an LLM trade the year step by step. Every run gets a look-ahead check and a record for papers; trend following made +21.1% against SPY's +12.1%. How →
• 0.6.3 · ⏳ Long runs keep going in the background: scans, backtests, agent runs and news fetches go on when you switch pages or reload, and a bar takes you back to the result.
• 0.6.2 · ❓ Every number explains itself: a ? next to every card, column and field says what it is, how it is calculated and how to use it, in English and 中文. See it →

• 0.6.1 · 🔎 The news behind every backtest trade: pick a trade and see the headlines the backtest had at that close and the order it placed. How →
• 0.6.0 · 🗞️ 2026 news in the box: 16,945 headlines and SEC filings for the 64 built-in stocks, so riskaware backtest --news works with nothing to download. The agent with news made +15.9% against SPY's +12.1%, with a -5.3% drawdown against -8.9%. Results →
• 0.6.0 · 🧪 Describe a strategy, the AI writes and tests it: over MCP, Claude, Codex or Gemini write the strategy as code; it is checked for look-ahead and side effects and runs in a separate process. How →
• 0.6.0 · 🔭 No peeking at the future: each backtest day sees only news published before its close, and a strategy cannot reach later prices. Details →
• 0.5.0 · 🔑 No API key needed: agent reviews run on your Claude, ChatGPT or Gemini plan with --llm claude-cli, codex-cli or gemini-cli. How →
• 0.5.0 · 🔌 MCP in one command: riskaware mcp-setup claude-desktop (or claude-code, codex, gemini, antigravity). Set it up →
• 0.5.0 · 🗄️ Your own news archive for other years: SEC 8-K filings for free, your Benzinga key, or any CSV, replayed the same way. How →
• 0.4.0 gave each agent its own LLM review with every decision on record, 0.3.0 added daily paper-trading agents, the MCP server and the new dashboard, and 0.2.0 added options backtests and four stock strategies.

The full history is in the changelog.

📸 Screenshots

Every page of the dashboard (riskaware dashboard), in English and 中文. Click a picture to open it full size.

💡 The idea

Most trading bots either chase every signal or need a quant team to configure. This one follows a simple, explainable discipline that long-term investors already use: buy quality stocks when they pull back to their moving averages, add when fear is high and the earnings still hold up, trim when prices run too far, never panic-sell into uncertainty, and always keep a cash reserve. Four agents check the market, the calendar, the company and the news; a deterministic risk manager has the final word on every order.

Not financial advice. It starts in paper mode, and live trading needs three explicit switches.

✨ Highlights

• Macro-aware market regimes. VIX and its term structure (VIX/VIX3M), sector breadth, credit appetite (HYG vs IEF), safe-haven demand, a fear-and-greed gauge computed from free data (and CNN's Fear & Greed for reference), and the FOMC, CPI, jobs report, PPI, GDP and PCE calendar put the market in one of four regimes: risk-on, neutral, uncertain, risk-off.
• Buy low, sell high. Pullbacks to EMA 50 / 100 / 200, RSI(2) and z-score mean reversion, quality dips that must pass an earnings check (revenue growth, margins, free cash flow, leverage, EPS beats), breakouts and trend continuation in strong markets. Take-profit trims when a stock runs far above EMA50; trend exits after a break of a falling EMA50.
• No panic selling. When the regime is uncertain or risk-off the agent holds, does not sell, and only buys at strong support. Only a disaster the company itself confirms (bankruptcy, delisting, restatement in its own 8-K or press release) or an optional hard stop can force an exit.
• Risk first. A 30% cash + T-bill floor, position, sector and speculative ("lottery ticket") caps, volatility-scaled sizes, buying i