alphacouncil-agent

<a name="readme-top"></a>

<div align="center">

<img src="assets/banner.png" alt="AlphaCouncil Agent" width="100%" />

<p> <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=20&duration=2800&pause=700&color=1A7A6A&center=true&vCenter=true&width=620&lines=Spawn+a+council+of+analyst+agents;Gather+sourced+evidence%2C+hide+nothing;Run+a+bull+vs+bear+debate;Get+a+PM+verdict%3A+Buy+%C2%B7+Hold+%C2%B7+Sell" alt="tagline" /> </p>

English · 中文 · 日本語

<p> <img src="https://img.shields.io/github/actions/workflow/status/Zhao73/alphacouncil-agent/check.yml?style=for-the-badge&label=build&logo=githubactions&logoColor=white&color=1a7a6a" alt="build" /> <img src="https://img.shields.io/badge/License-MIT-c9a227?style=for-the-badge" alt="MIT" /> <img src="https://img.shields.io/badge/Node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" /> <img src="https://img.shields.io/github/stars/Zhao73/alphacouncil-agent?style=for-the-badge&logo=github&color=0d4d4d" alt="stars" /> </p> <p> <img src="https://img.shields.io/badge/OpenAI_Codex-412991?style=for-the-badge&logo=openai&logoColor=white" alt="codex" /> <img src="https://img.shields.io/badge/Claude_Code-D97757?style=for-the-badge&logo=anthropic&logoColor=white" alt="claude code" /> <img src="https://img.shields.io/badge/MCP-compatible-000000?style=for-the-badge" alt="mcp" /> </p>

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

---

<div align="center">

<img src="assets/demo.gif" alt="AlphaCouncil Agent demo" width="100%" />

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

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

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

<div align="center">

<a href="https://star-history.com/#Zhao73/alphacouncil-agent&Date"> <img src="https://api.star-history.com/svg?repos=Zhao73/alphacouncil-agent&type=Date" width="640" alt="Star History Chart" /> </a>

<br/><br/>

<picture> <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png" /> <img src="assets/logo.png" alt="AlphaCouncil" width="120" /> </picture>

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

<a href="#readme-top">↑ Back to top</a>

</div>