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** · [中文](README.zh-CN.md) · [日本語](README.ja.md)

<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/OpenCode-1a7a6a?style=for-the-badge&logoColor=white" alt="opencode" />
  <img src="https://img.shields.io/badge/Grok_Build-000000?style=for-the-badge&logo=x&logoColor=white" alt="grok build" />
</p>
<p>
  <img src="https://img.shields.io/badge/MCP-compatible-000000?style=for-the-badge" alt="mcp" />
  <img src="https://img.shields.io/badge/API_keys-none_required-2ea043?style=for-the-badge" alt="no api keys" />
  <img src="https://img.shields.io/badge/dependencies-zero-2ea043?style=for-the-badge" alt="zero dependencies" />
</p>

<p>
  <a href="docs/INSTALL.md"><b>Install</b></a> ·
  <a href="#-usage"><b>Usage</b></a> ·
  <a href="#-tools--31-all-keyless"><b>Tools</b></a> ·
  <a href="#-the-bench--27-investor-method-lenses"><b>The bench</b></a> ·
  <a href="#-architecture"><b>Architecture</b></a> ·
  <a href="CHANGELOG.md"><b>Changelog</b></a> ·
  <a href="#-disclaimer"><b>Disclaimer</b></a>
</p>

</div>

---

<div align="center">

<img src="assets/demo.gif" alt="AlphaCouncil live: a council of analyst agents researching a ticker and debating to a verdict" width="100%" />

<sub><i>A real run, in real time. Want the still version? <a href="assets/run-example.png">Six lenses reaching the same call for different reasons</a> · <a href="docs/examples/final_report.SOX.zh.md">a complete real report</a> (SOX, full council, zh)</i></sub>

</div>

**Ask an LLM "is this stock a buy" and you get one confident paragraph of training-data
vibes. Ask AlphaCouncil and you get an argument** — eight evidence agents pull the primary
sources, twenty-seven investor-method lenses read the same facts and disagree in public,
bull and bear cross-examine each other for three rounds, and a portfolio manager signs a
verdict with entry bands and the conditions that would invalidate it. Every claim traces
to a source ID; a method whose inputs are missing says so instead of guessing.

Watch it happen live: the bundled [terminal client](#terminal-client-tui) plays the
council as a meeting transcript — each master speaking under a stance-colored name,
statements typing out character by character.

AlphaCouncil is a Codex and Claude Code plugin. Full council is the default; an explicitly
requested `quick` run uses a smaller, plugin-managed headless contract. Both gather sourced
evidence, run selected method seats and produce an auditable portfolio-manager report.

### ✨ Why AlphaCouncil

| | |
|---|---|
| 🏛️ **A council, not one opinion** | Eight specialist analysts by default, eleven available — market data, earnings, forward expectations, quant, valuation, news and supply chain, insider/SEC, IB events, macro, narrative, crowding. |
| 🎭 **27 selectable investor lenses** | Buffett, Munger, Graham, Lynch, Marks, Damodaran, Ackman, Cathie Wood, Pabrai, Bogle and more read the **same facts** through different stated research priorities. Every council run shows all 27 with actual maturity before research. Full accepts any non-empty selection or `all`; quick requires 1-4 and rejects `all`. |
| 🧺 **A basket is not a company, and the bench knows it** | An ETF or index is priced by look-through: a fund owning 1% of a business has a claim on 1% of its owner earnings, so a company method reads a basket **without changing its method**. Ratios aggregate by weight; absolute figures become the fund's own dollar claim; a share count is refused because it has no portfolio meaning. |
| 📰 **A basket gets its own industry news** | `SOX` has no press office. Its industry is derived from the weighted SIC groups of its holdings, so SOXX resolves to semiconductors and survives a rebalance. Where no group dominates, the basket is queried as the several industries it actually is. |
| 🌏 **What else you are betting on** | Correlation to the broad market, to KOSPI, to KOSDAQ and to the semiconductor cycle, plus dispersion across the eleven sector SPDRs. Sessions pair by date, because Korea and the United States keep different holidays. |
| 💵 **Fund flow that refuses to be faked** | Creations minus redemptions, priced. Only a filed share count or the issuer's own assets-over-NAV identity may price a flow; a count reconstructed from positions is refused, because a difference cancels the number and keeps the error. |
| 🐂🐻 **Adversarial by design** | Full runs a three-round bull/bear cross-exam and the visible/deep path can add three adversarial verifiers. Quick runs one parallel bull/bear statement round and a short PM; it checks scoped source IDs but explicitly does not claim adversarial verification. |
| ⏱️ **You pick the depth: 15, 30 or 60 minutes** | The run asks before it starts and shows the expected time beside the hard ceiling for each tier — you never type a speed. All three are the same full contract: eight analysts, three debate rounds, the PM. What changes is how long each seat may think, and a tier shapes the output too, because a shorter fuse on the same prompt buys unfinished work rather than faster work. Plugin-managed full starts all eight analysts together, runs Bull/Bear together inside each round, and persists a terminal run inside the chosen tier. Provider failures produce an explicit `incomplete` result, never silently missing seats. |
| 🔍 **Auditable, never hallucinated** | Every claim maps to a source ID. A screen rule with missing inputs is `skipped`, never a pass. An undated headline is excluded, not shown as recent. Gaps are a section, not an omission. |
| 🧭 **Company, ETF and index routing** | The symbol is classified before research. Companies use issuer financials; ETFs use dated holdings look-through; indices use aggregate methodology. QQQ/SPY are never treated as companies with their own revenue or EPS. |
| 💰 **Entry price bands, not one number** | Three conditional bands with what each depends on. "The cycle position is undetermined" changes what the bands are conditional on; it does not excuse leaving them out. |
| 🔑 **31 tools, zero API keys, zero dependencies** | SEC EDGAR, CBOE options, Yahoo/Stooq quotes, 21 macro series, news and social — all keyless. `node mcp/server.mjs` and nothing else. |
| 🖥️ **One contract on four hosts** | Claude Code, Codex, OpenCode and Grok Build share the same selection, evidence and reporting gates. Quick is always executed by the plugin-managed headless `analyze_symbol` path. |

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

## What this ships

`npm install -g alphacouncil-agent` installs the current release.

Twenty-seven method seats, each running its own formulas and its own thresholds against typed
facts built from SEC filings, FRED series, issuer holdings disclosures, published index
aggregates, Section 16 ownership, cross-market price history and dated industry news.
Fifty-four executable tools.

Measured against live grounding, with no fixtures: every one of the 27 seats reaches a stance
somewhere across a mixed set of symbols, with no contract failures. A basket that had **no data
path at all** — `SOX` was in neither registry — now produces 40-plus typed facts, and the seats
that read them are running the same methods they run on a company.

Honesty note: seat formulas are AI-authored reconstructions of named published methods,
pending human review — the governance status and what remains open are tracked in
[the v1.0.0 release contract](docs/releases/v1.0.0.md), and `npm run check` prints
exactly where that stands.

Trust posture: zero runtime dependencies, no install scripts, no telemetry, every data
source keyless and public; analyst workers run in a read-only sandbox
(`codex exec -s read-only -a never --ephemeral`). Details in [SECURITY.md](SECURITY.md).

See [the v1.0.0 release contract](docs/releases/v1.0.0.md) for the exact ETF/index and full/quick
boundary and [the report contract](docs/report-contract.md) for `quick_v1` versus `full_v2`.

## 📜 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](docs/INSTALL.md)** for full Codex and Claude Code setup. **Windows users:** see the [Windows section](docs/INSTALL.md#windows).

**Prerequisites:** Node.js >= 18. The headless research path also needs an
installed, authenticated **Codex CLI** (each analyst worker runs as `codex