alphacouncil-agent

English · 中文 · 日本語

<p> <a href="#-usage"><b>Usage</b></a> · <a href="docs/INSTALL.md"><b>Install</b></a> · <a href="#-architecture"><b>Architecture</b></a> · <a href="#-disclaimer"><b>Disclaimer</b></a> </p>

</div>

---

<sub><i>One command → a council of analyst agents → bull/bear debate → a portfolio-manager verdict.</i></sub>

</div>

AlphaCouncil Agent is a Codex and Claude Code plugin for full public-equity research workflows. It coordinates multiple analyst agents, gathers sourced evidence, runs bull/bear debate, and produces a portfolio-manager style final report.

✨ Why AlphaCouncil

| | | |---|---| | 🏛️ A council, not one opinion | 11 specialist analyst agents (market data, earnings, valuation, quant, insider/SEC, IB events…) run in parallel. | | 🐂🐻 Adversarial by design | A structured bull vs bear debate, refereed by a portfolio-manager agent that issues an actual rating. | | 🔍 Auditable, never hallucinated | Every claim maps to a source ID. Missing data is listed in a "data gaps" section — never hidden. | | ⏱️ Multi-horizon verdict | Buy/Hold/Sell plus separate 1-4 week, 3-6 month, and 12-month views. | | 🔑 No data vendor, no API keys | No financial-data API, market-data feed, or brokerage login. Analysts gather evidence live via the agent's own web search (Codex web search / Claude Code WebSearch + WebFetch) — billed only to your existing Codex / Claude Code subscription. MIT licensed. | | 📚 Bundled research playbooks | Public-equity-investing & investment-banking methodology ship as local skills — no dependency on Codex-only remote workflows, so Claude Code gets the same research depth (skills/public-equity-investing, skills/investment-banking). | | 📈 Real market data, no key | Built-in get_quote pulls delayed (~15m) index / index-futures (incl. night session) / FX / rates / vol / commodity / stock levels via Yahoo + Stooq — no API key, so analysts cite real numbers, not guesses. |

This repository is the uploadable source copy. Runtime outputs are written outside the repo under ~/.alphacouncil-agent/runs/<run_id>/.

📜 Disclaimer

This software is for educational and research purposes only. It is not investment advice, not a recommendation to buy or sell any security, and not a solicitation. AI-generated analysis can be incomplete, outdated, or wrong. Do your own research and consult a licensed financial professional before making any investment decision. The authors accept no liability for any loss.

Install

See docs/INSTALL.md for full Codex and Claude Code setup. Windows users: see the Windows section.

Prerequisites: Node.js >= 18. The headless research path also needs an installed, authenticated Codex CLI (each analyst worker runs as codex exec). On Windows, v0.3.0+ launches the CLI through cmd.exe and feeds prompts over stdin so native codex.cmd installs work without WSL in the normal case.

# Codex
codex plugin marketplace add Zhao73/alphacouncil-agent
# then run `codex`, open /plugins, install, and /reload-plugins

# Claude Code
/plugin marketplace add Zhao73/alphacouncil-agent
/plugin install alphacouncil-agent@alphacouncil
/reload-plugins

🚀 Usage

Just talk to it. Mention the agent and a ticker or a question:

@alphacouncil-agent analyze NVDA as a long/short pitch
@alphacouncil-agent is AAPL a buy at current levels?
@alphacouncil-agent compare TSLA vs RIVN for a 12-month horizon
@alphacouncil-agent 帮我看看 700.HK 现在能不能买
@alphacouncil-agent トヨタ(7203)を分析して

You get back a single, chat-readable report:

VERDICT: Overweight  (confidence: medium)
├─ Analyst work log ........ 11 evidence agents, 38 sourced claims
├─ Bull thesis ............. demand inflection, margin expansion, buyback
├─ Bear thesis ............. valuation, customer concentration, cycle risk
├─ Short / medium / long ... 1-4wk · 3-6mo · 12mo views
├─ Catalysts & risks ....... earnings, guidance, regulatory
├─ Data gaps ............... explicitly listed, never hidden
└─ Source table ............ every claim mapped to <task>:<source_id>

The concise handoff is written to ~/.alphacouncil-agent/runs/<run_id>/user_response.md. The full report is written to ~/.alphacouncil-agent/runs/<run_id>/final_report.md, with analyst Markdown files and artifact_index.md in the same run directory.

What It Does

Default stock-analysis runs are full runs, not lite summaries:

Market data and price action
Earnings deep dive
Forward expectations and implied beat/miss thresholds
Sell-side rating and target-price revisions
Earnings-call management signals
Quant factor view: momentum, trend, volatility, volume/liquidity, relative strength, short interest, borrow, option IV/skew/expected move when available
Valuation and long/short pitch
News, industry context, CEO/management and public industry voices
SEC filings, Form 4 insider transactions, buybacks, dilution, debt and capital allocation
Investment-banking event analysis for M&A, ECM, debt, buyback or strategic transactions
Bull researcher, bear researcher and portfolio manager synthesis

The final report must be readable directly in chat. It includes analyst work logs, data/news/filing summaries, bull/bear debate, portfolio-manager verdict, short/medium/long-term view, data gaps, confidence and source table.

🧩 Architecture

flowchart TD
    U["@alphacouncil-agent<br/>ticker / question"] --> SK["SKILL.md<br/>runtime instructions"]
    SK --> AG{{"Analyst Council"}}
    AG --> A1["📈 Market Data"]
    AG --> A2["💰 Earnings"]
    AG --> A3["⚖️ Valuation"]
    AG --> A4["🧮 Quant Factors"]
    AG --> A5["🏛️ Insider / SEC"]
    AG --> A6["🤝 IB Events"]
    A1 --> EV[("Evidence Base<br/>sourced packets")]
    A2 --> EV
    A3 --> EV
    A4 --> EV
    A5 --> EV
    A6 --> EV
    EV --> BULL["🐂 Bull Researcher"]
    EV --> BEAR["🐻 Bear Researcher"]
    BULL --> PM{{"Portfolio Manager"}}
    BEAR --> PM
    PM --> R[["final_report.md<br/>Buy · Hold · Sell"]]

Key files:

.codex-plugin/plugin.json - Codex plugin metadata.
.mcp.json - MCP server wiring.
assets/logo.png - plugin icon used by Codex.
skills/alphacouncil-agent/SKILL.md - runtime instructions for Codex.
mcp/server.mjs - JSON-RPC MCP server and workflow implementation.
scripts/selfcheck.mjs - minimal regression check.

🆚 Codex vs Claude Code edition

Both editions share the same workflow, JSON packet contract, audit artifacts, the no-API-keys / live-web evidence model, and the same disclaimer. The Claude Code edition changes only how the council is run.

| | Codex edition | Claude Code edition | |---|---|---| | Council execution | codex exec workers, concurrency-capped | All 11 analysts as parallel Task subagents, one fan-out | | Per-analyst context | Separate process | Separate subagent, full isolated context window | | Evidence | codex exec --search | WebSearch + WebFetch in each analyst's own context | | Evidence → debate | Sequential | Hard barrier on the run's phase machine | | Debate depth | 3 rounds (case / rebuttal / Q&A), server-run | 3 rounds, bull + bear in parallel per round | | Claim verification | Missing-source gate (run flagged, report banner) | + per-claim adversarial verify: re-fetch cited URL, re-derive, refute (host-driven) | | Full-run enforcement | Incomplete runs marked incomplete (server gate) | Same gate, plus a hard barrier before debate | | Model & cost | One model | Pick per role — evidence on Sonnet, debate/verdict on Opus 4.8 (or all-Opus / all-Sonnet) | | Language | User's language | User's language across every subagent + the live workflow |

Honest scope: same model family, same prompts, same audit contract — the win is context isolation, always-on parallel fan-out, and deterministic gates, not a smarter model. As of v0.3.0 the shared server runs the 3-round debate, enforces missing-source / full-run / report-quality gates, writes concise and full report artifacts, and supports native Windows Codex CLI launching. As of v0.3.1, the plugin also bundles agent-skills-governance, an addyosmani/agent-skills-style anti-laziness skill with explicit stop gates and exit criteria. The Claude Code edition adds parallel per-round execution and host-driven per-claim verification. Live-web staleness and paywalls limit both editions equally.

Data Contract

Evidence agents return JSON packets:

{
  "task": "market_data",
  "symbol": "NVDA",
  "as_of": "YYYY-MM-DD",
  "summary": "string",
  "claims": [
    {
      "claim": "string",
      "evidence": "string",
      "confidence": "high|medium|low",
      "source_ids": ["market_data:S1"]
    }
  ],
  "metrics": {},
  "sources": [
    {
      "id": "market_data:S1",
      "title": "string",
      "url": "https://example.com",
      "published_at": "YYYY-MM-DD or unknown",
      "retrieved_at": "YYYY-MM-DD"
    }
  ],
  "open_questions": ["missing data item"],
  "confidence": "high|medium|low"
}

All source IDs are task-scoped as <task>:<source_id>. Missing data must be reported in open_questions and in the final report's data-gap section.

Run Locally

npm run check

The check validates:

MCP server syntax
tool schema exposure
source ID scoping
default real-run behavior
visible-run recording
events.jsonl, status.json, all_agents.md, source_manifest.json
final_report.md, user_response.md, artifact_index.md, report_quality.json
one Markdown file per evidence analyst plus bull, bear, and portfolio manager
final report includes analyst work log, bull/bear debate record and data gaps

Codex Install Shape

The plugin expects this local layout:

.codex-plugin/plugin.json
.mcp.json
skills/alphacouncil-agent/SKILL.md
mcp/server.mjs
scripts/selfcheck.mjs
package.json

.mcp.json runs:

{
  "mcpServers": {
    "alphacouncil-agent": {
      "command": "node",
      "args": ["./mcp/server.mjs"],
      "cwd": "."
    }
  }
}

Notes

This is an independent Codex plugin implementation. It uses a multi-agent investment-committee workflow: analyst teams, evidence sharing, bull/bear debate and portfolio-manager synthesis.

No API keys, brokerage credentials, private filings or generated run artifacts should be committed.

⭐ Star History

If AlphaCouncil saved you time, consider leaving a ⭐ — it genuinely helps.

</div>

✨ Why AlphaCouncil

📜 Disclaimer

Install

🚀 Usage

What It Does

🧩 Architecture

🆚 Codex vs Claude Code edition

Data Contract

Run Locally

Codex Install Shape

Notes

⭐ Star History

Related MCP servers

MCP servers by category