alphacouncil-agent

English · 中文 · 日本語

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

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

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.

Related MCP server: deeplook

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.

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.

↑ Back to top