invest — openInvest Claude Code plugin

Self-hosted multi-asset AI investment committee for Claude Code. View your portfolio and live prices, track any yfinance symbol (A-share / HK / US / ETF / crypto / commodity, any currency), and run a 4-role LLM committee that debates and returns a BUY / ACCUMULATE / HOLD / TRIM / SELL verdict with a written memo.

中文完整文档见仓库根 README.md 与 docs/wiki。

Install

Claude Code:

/plugin marketplace add longsizhuo/openInvest
/plugin install invest@openinvest

Codex (same plugin, via the Codex marketplace):

codex plugin marketplace add longsizhuo/openInvest
codex plugin add invest@openinvest

Codex reads the same SKILL.md (agentskills.io). For the MCP tools, register the server once after the backend bootstraps:

codex mcp add openinvest --env INVEST_HOME=$HOME/openInvest -- uvx openinvest-mcp

Hermes Agent:

hermes plugins install openinvest --enable

That installs the version listed in Hermes's official plugin catalog (a reviewed, pinned commit), and the backend version that run.sh pins comes with it — so a catalog install can lag main in both skills and MCP tools. For the newest commit on main instead, install by repo path: hermes plugins install longsizhuo/openInvest/plugin --enable. For the MCP tools, add this to ~/.hermes/config.yaml (or run the commands Hermes shows right after install; onboarding also adds it when missing). It runs the plugin's own run.sh, which pins the backend to the version this plugin release was built with (the plugin is installed in $HERMES_HOME/plugins/openinvest; replace YOU, and adjust the path if HERMES_HOME is not ~/.hermes). The server is registered twice because Hermes' trust: untrusted asks on every call: the agent scope (reads, news queue, committee, daily report) runs with full trust so cron jobs work, and the ledger scope (tools that move money) stays untrusted, so Hermes asks before each ledger write.

mcp_servers:
  openinvest:
    command: bash
    args: ["/home/YOU/.hermes/plugins/openinvest/skills/invest/scripts/run.sh", "mcp"]
    env: {INVEST_MCP_SCOPE: agent}
  openinvest_ledger:
    command: bash
    args: ["/home/YOU/.hermes/plugins/openinvest/skills/invest/scripts/run.sh", "mcp"]
    env: {INVEST_MCP_SCOPE: ledger}
    trust: untrusted

Then in chat say "set up invest" / 帮我初始化 invest — a short onboarding (name, risk tolerance, current holdings) writes your config. On Hermes it also creates two cron jobs (openinvest-daily committee report, openinvest-sentinel news triage; they run on your model quota, hermes cron remove <id> turns them off), and the plugin injects a one-paragraph ledger digest at session start so questions about your tickers reach openInvest. The digest goes into group chats as well (anyone in the group can read your ticker list); plugins.entries.openinvest.settings.inject_digest: false keeps only the routing rule. While the host runs, the MCP server keeps a background scheduler alive (news queue, price sentinel, NAV snapshots, daily backup); run.sh service install keeps it running when the host is closed. API keys never go through the chat: add LLM_API_KEY (and optional EMAIL_*) to ~/openInvest/.env yourself; the Coordinator path needs no key at all. After that just ask things like "show my portfolio", "how's my P&L", "should I buy AAPL", or "run committee on gold".

What actually gets installed

The plugin ships the agent skill layer (invest + invest-setup) plus an MCP server (.mcp.json, auto-registered on install — tools include status, live_prices, decisions, explain_decision, record_execution, buy, sell, run_committee, …). The backend ships on PyPI (openinvest): on first call run.sh fetches it via uvx (cached by uv, no clone, no venv juggling) and keeps your data in ~/openInvest (portfolio, ledgers, .env). The backend version is pinned in run.sh and moves with each plugin release, so updating the plugin updates the backend. Nothing is installed system-wide.

First-run note: the very first call downloads the package from PyPI (a few seconds); if the first MCP connect times out, just retry once — after that uvx serves from cache and MCP starts in ~1s.

Remote hub? (BETA) If your data lives on a central hub running openinvest-mcp --http, skip the local server and connect over HTTP instead: claude mcp add --transport http openinvest https://<hub>/mcp --header "Authorization: Bearer $INVEST_API_TOKEN"

Division of labor (per issue #133): MCP tools = what the agent can call; skills = how to orchestrate the committee (Coordinator protocol, decision discipline). Your agent keeps conversation, memory, and personalization; openInvest keeps the investing.

Two ways to run the committee:

• Coordinator (default in Claude Code): Claude spawns the 4 roles as subagents — no API key needed, no third-party LLM token cost.
• Direct (any agent / script): run.sh run_committee <SYM> runs the 4 roles via a backend LLM — needs DEEPSEEK_API_KEY.

The 4 roles: Macro Strategist (VIX / rates / FX), Quant Analyst (technicals, blind to your holdings), Risk Officer (concentration / tail risk, blind to the signals), then a CIO synthesizes a verdict + confidence. The system never places orders — decisions stay with you.

Requirements

• Claude Code
• uv — the launcher checks for it and tells you how to install if missing (backend + Python come from PyPI via uvx)
• Optional: DEEPSEEK_API_KEY (only for the Direct path / cron daily report)

Disclaimer

LLM-driven decision-support tool. Not investment advice. LLMs make mistakes, get overconfident, and miss things. The system never auto-trades — try what_if on a small amount for two weeks before using real money. The internal ledger (db/trades_db.py) is a local SQLite record and does not connect to any real payment or brokerage. Any public hit-rate / PnL data is the author's own account history; past performance does not predict future returns.

Links

• Repository & full docs: https://github.com/longsizhuo/openInvest
• Wiki: https://github.com/longsizhuo/openInvest/tree/main/docs/wiki
• License: MIT