A Claude-Code-native AI swarm for answering hard, multi-perspective questions. You ask a question; an orchestrator (Claude) designs a custom cohort of 5–30 persona-subagents, spawns them in parallel, lets each one independently research and reason, then synthesizes the swarm into a single answer that surfaces both consensus and dissent.

Built for questions where one agent's view isn't enough:

• Forecasting — "Will silver hit $40/oz by July?"
• Geopolitical analysis — "What happens next with the war in Iran?"
• Decision support — "Should I rotate equities into commodities?"
• Research deep-dives — "What's the current state of fusion commercialization?"

Inspired by Anthropic's multi-agent research system, the Wisdom of the Silicon Crowd ensemble forecasting paper, and Tetlock's superforecasting principles.

THIS SYSTEM USES A LOT OF TOKENS. A LOT. Every question spawns 15 agents by default (configurable), each doing 8–15 web searches plus its own reasoning. A typical run consumes a few million tokens — the equivalent of dozens of normal Claude conversations packed into a single question.

How tokens are consumed (important): This swarm is designed to run inside a Claude Code session. It does not call the Anthropic API directly from custom code. Every Claude token the swarm uses — orchestrator, subagents, synthesis, retrospective — flows through Claude Code itself, which means it bills exactly the way your Claude Code authentication is set up:

• Subscription users (Pro / Max / Team / Enterprise) — the typical case: all Claude tokens come out of your plan's allowance. There are no separate per-token API charges. You consume plan capacity instead of paying invoices.
• Console / API-credit users: if you authenticated Claude Code with an Anthropic Console account instead of a subscription, then yes — every token the swarm uses bills against your Anthropic API credit balance at standard pay-per-token rates. A 15-agent run can run you several dollars at Opus pricing. Watch the Console carefully.

The only pay-per-use charges that this project itself introduces (independent of how you authenticate Claude Code) come from the optional Grok integration, which calls OpenRouter for Grok 4 — those are always billed separately to your OpenRouter account.

Before you ever run this, you need to know what you're doing about cost:

• You control the cohort size. When you ask the orchestrator a question, you can specify how many agents to use — e.g. "use 5 agents" for a cheap test, "use 20 agents" for a deeper run. Default is 15. Smaller cohorts cost roughly proportionally less. Always start small when you're new or when testing changes.
• Strongly recommended: a Claude Max plan. The Pro plan will hit its weekly usage limits very quickly with this kind of workload — a few full runs per week will exhaust it. Max gives you meaningfully more headroom but it's still finite, so you can't run dozens of swarms a day even on Max.
• Monitor your plan usage in real time. Always.
  • Inside any Claude Code session, run /cost to see the current session's running token totals.
  • Check your plan-level usage at claude.ai/settings — this is where you see how much of your Pro/Max allowance you've consumed.
• Test with small cohorts first. Before running a 20-agent Opus-tier swarm, prove the orchestrator behaves correctly on a 5-agent run. Iterate cheap, then scale up.
• Runs are slow. Expect an hour or more of wall-clock time per run, sometimes longer when Anthropic's servers are busy. This is not a tool for impatient questions — once you approve the cohort, walk away from the computer and come back later.
• Optional Grok integration uses real money via OpenRouter — separate from your Claude Code plan. Each Grok agent in a mixed cohort costs roughly $0.15–0.50 in OpenRouter charges (Grok 4 is a reasoning model; the higher end is for complex questions where it does deeper reasoning and more web/X searches). See the Grok section below and monitor your balance at openrouter.ai/credits.

You are responsible for monitoring your own plan usage and any OpenRouter charges. See the full Disclaimer at the bottom of this README before using.

1. You start a Claude Code session in this folder and ask a question.
2. CLAUDE.md auto-loads and primes Claude as the orchestrator.
3. The orchestrator creates a runs/<date>_<slug>/ folder, designs a custom cohort of personas for your specific question, and spawns them all in parallel via the Agent tool.
4. Each persona-subagent reads agent-workflow.md, does its own web research (and optionally Python analysis), and writes a structured analysis to its own subfolder.
5. The orchestrator synthesizes everything into synthesis.md, answer.md, and a retrospective.md evaluating the cohort itself.
6. You read the answer; future runs read past retrospectives so the swarm sharpens over time.

• Claude Code — the swarm runs inside a Claude Code session, not as a standalone script.
• Python 3.13+ — for the shared analysis venv.
• Windows / macOS / Linux — fully portable. The orchestrator detects the platform and resolves the right venv binary path at the start of every session.
• An active Claude Code plan — Pro, Max, Team, or Enterprise. The swarm runs inside a Claude Code session and consumes tokens from your plan allowance, not via direct API calls. Claude Max is strongly recommended because the Pro weekly limits are too small for repeated runs.

The swarm runs inside a Claude Code session, so you need Claude Code first. The official install docs are at code.claude.com/docs/en/setup — check there for the current canonical instructions. The native installer is the recommended method and auto-updates in the background.

macOS, Linux, WSL (recommended):

curl -fsSL https://claude.ai/install.sh | bash

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex

Windows users: Claude Code uses Git Bash internally to run commands. Install Git for Windows before installing Claude Code if you don't already have it.

Alternative install methods:

# Homebrew (macOS / Linux) — manual updates only
brew install --cask claude-code

# WinGet (Windows) — manual updates only
winget install Anthropic.ClaudeCode

There's also a Desktop app for macOS and Windows if you prefer a GUI over the terminal. The npm package (@anthropic-ai/claude-code) still works but is now deprecated in favor of the native installer.

System requirements: macOS 13+, Windows 10 1809+, Ubuntu 20.04+, Debian 10+, Alpine 3.19+, 4 GB RAM, internet connection.

Authentication: Claude Code requires a Pro, Max, Team, Enterprise, or Console account (the free Claude.ai plan does not include Claude Code access). After installing, run claude and follow the browser prompts to authenticate.

Verify the install:

claude --version
claude doctor   # detailed install + config check

git clone <your-fork-url> the-swarm
cd the-swarm

python -m venv .venv

# Windows:
.venv/Scripts/python.exe -m pip install --upgrade pip setuptools wheel
.venv/Scripts/python.exe -m pip install -r requirements.txt

# macOS / Linux:
.venv/bin/python -m pip install --upgrade pip setuptools wheel
.venv/bin/python -m pip install -r requirements.txt

# Windows:
.venv/Scripts/python.exe -c "import numpy, pandas, scipy, statsmodels, sklearn, yfinance, arch, matplotlib, seaborn; print('OK')"

# macOS / Linux:
.venv/bin/python -c "import numpy, pandas, scipy, statsmodels, sklearn, yfinance, arch, matplotlib, seaborn; print('OK')"

That's it. No additional config or API keys to set up beyond whatever Claude Code already uses.

cd the-swarm
claude

Then in the Claude Code session, just ask:

What is most likely to happen to the price of silver between now and the end of May 2026? Use 10 agents.

The orchestrator handles the rest. You can specify the agent count (use 20 agents, small swarm of 8) or omit it for the default of 15.

Watch the run progress in runs/<date>_<slug>/ as it builds. Final answer lands in runs/<date>_<slug>/answer.md.

By default the swarm runs Claude-only. There's an optional integration that lets the orchestrator delegate 2-4 personas to Grok 4 via OpenRouter for lenses where real-time web + X (Twitter) search adds value (sentiment, breaking news, social signal). Grok has native X/Twitter search that Claude's WebSearch cannot match — which makes it genuinely additive on news/social-heavy questions, not just "another model for variety's sake."

To enable it (one-time setup):

python grok_mcp/install.py

That script:

1. Installs the MCP dependencies (mcp, python-dotenv, openai) into your venv
2. Generates .mcp.json at the project root with platform-specific absolute paths
3. Creates .env from .env.example

Then add your OpenRouter API key to .env:

# .env
OPENROUTER_API_KEY=sk-or-v1-...

Get a key at https://openrouter.ai/keys. Restart your Claude Code session — you'll see a one-time prompt to approve the project-scoped MCP server. After that, the orchestrator detects the Grok availability automatically and will design mixed Claude+Grok cohorts for relevant questions. You see the proposed cohort once, approve it, and the run goes unattended.

Cost: roughly $0.15–0.50 per Grok agent on top of your Claude Code plan consumption. See grok_mcp/README.md for details.

the-swarm/
├── CLAUDE.md            # Orchestrator playbook — auto-loads in any Claude Code session here
├── agent-workflow.md    # Persona subagent playbook — every spawned Claude agent reads this
├── requirements.txt     # Pinned Python stack (numpy, pandas, yfinance, statsmodels, mcp, ...)
├── README.md            # This file
├── .gitignore           # Excludes .venv/, .env, .mcp.json, and per-run outputs
├── .env.example         # Template for OPENROUTER_API_KEY (real .env is gitignored)
├── .mcp.json.example    # Template for the Grok MCP config (real .mcp.json is gitignored)
├── grok_mcp/            # Optional Grok-via-OpenRouter integration
│   ├── grok_swarm_mcp.py  # FastMCP server exposing ask_grok
│   ├── install.py         # one-time setup
│   └── README.md          # Grok integration docs
└── runs/
    ├── README.md        # Per-run folder convention
    └── <date>_<slug>/   # Created per question (gitignored — your runs are private)

• .venv/ — recreate it from requirements.txt. Saves cloning hundreds of MB.
• .env — your OpenRouter API key is yours alone. .env.example is the committed template.
• .mcp.json — generated by grok_mcp/install.py with absolute paths specific to your machine. .mcp.json.example is the committed template.
• runs/<your runs>/ — your question history is private. Only runs/README.md is tracked.
• Persona libraries / fixed templates — personas are designed fresh per question by the orchestrator. A fixed library would just become a crutch.

Both CLAUDE.md and agent-workflow.md are meant to be iterated on. After each run, the orchestrator writes a retrospective.md evaluating which personas worked, which didn't, and what to do differently — read those over time and tighten the prompts in the playbooks accordingly.

If you want different default behavior (cohort size, source quality bar, output format, additional Python packages), edit the playbooks directly. There's no separate config file by design.

See the READ THIS FIRST warning at the top of this README for the headline — this section is the detail.

This swarm runs inside Claude Code. The Claude side does not call the Anthropic API directly — it consumes your Claude Code plan's token allowance (Pro, Max, Team, etc.). The only thing on this project that bills per request is the optional Grok integration, which goes through OpenRouter.

• Plan consumption (Claude side): every run draws from your Claude Code plan allowance. Pro is too small for regular use — a couple of full runs will exhaust your weekly limit. Max is the realistic minimum for using this tool more than occasionally, and even on Max you can't run dozens of swarms a day.
• OpenRouter charges (Grok side, optional): if you enable the Grok integration, each Grok agent in a mixed cohort costs roughly $0.15–0.50 in OpenRouter charges. Grok 4 is a reasoning model — internal reasoning tokens count against the output budget, so complex questions land at the upper end of that range. A typical 15-agent run with 3 Grok agents adds ~$0.45–$1.50 on top of your plan consumption.
• Wall clock: typically an hour or more per run, sometimes considerably longer when Anthropic's servers are busy or rate-limited. Claude Code runs ~7 subagents concurrently and queues the rest, so a 15-agent cohort comes back in waves. Grok agents (if enabled) add their own variable latency on top — a single Grok call with web + X search can take 30–90 seconds. Don't sit and watch the spinner. Once you've approved the cohort, walk away — make a coffee, do something else, come back later.
• Token breakdown (rough order of magnitude — varies by question depth):
  • Each Claude subagent: ~50K–200K tokens (its own context + tool calls + reasoning)
  • 15 agents × ~100K avg = ~1.5M tokens consumed from your plan per run
  • Synthesis pass: 50K–200K tokens
  • The orchestrator session itself: another 100K+ for setup, planning, retrospective

You should be in the habit of checking usage during a run, not just after:

• Inside Claude Code (plan consumption): the /cost slash command shows the current session's running token totals at any time. Run it after each step if you want to track the burn live.
• Account-level (Claude plan): claude.ai/settings — your Pro/Max usage dashboard, where you can see how much of your weekly/monthly allowance you've used.
• Grok integration (real money): openrouter.ai/credits — your OpenRouter credit balance and per-request usage. This is the only place actual dollars come out for this project.

If you're tweaking the playbooks and want to test changes without burning a fortune:

• Start with 5–8 agents instead of 15. Same flow, half the cost.
• Use a simple test question with a known answer first. Verify the orchestrator behaves before pointing it at a real, expensive question.
• Watch the first few agents complete before letting the full batch run. If something is wrong, kill the session early.

It's not a chatbot. It's not for quick lookups. It's not for questions where one Google search would do. Don't use it casually. Every run is a real cost. Use it when you want a serious multi-perspective answer to a question that genuinely benefits from one — and treat each run as a deliberate decision.

• How we built our multi-agent research system — Anthropic's orchestrator-worker pattern
• Wisdom of the silicon crowd — LLM ensemble forecasting matching human crowd accuracy
• Multi-LLM-Agents Debate (ICLR 2025) — why naive debate often fails to beat single agents (and what does work)
• Tetlock — Good Judgment Project — superforecasting principles baked into the agent workflow

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. By using this project, you acknowledge and accept the following:

• You are solely responsible for any token consumption, plan usage, OpenRouter charges, or other costs incurred from running this swarm. This swarm runs inside Claude Code and consumes tokens from your Claude Code plan allowance (Pro, Max, Team, Enterprise — whichever you have). If you enable the optional Grok integration, you are also responsible for any OpenRouter charges that result.
• This system uses a lot of tokens — see the READ THIS FIRST warning at the top of this README. The author of this project is not responsible for plan limits being exhausted, rate-limit lockouts, unexpected OpenRouter charges, or any other usage-related consequence.
• It is your responsibility to monitor your own plan usage and any OpenRouter balance, set your own spending limits where the platform allows, and stop runs that are costing more than you want to spend.

• The swarm produces opinions from LLM personas based on web research and reasoning. Outputs may be wrong, biased, hallucinated, outdated, or otherwise unreliable despite the anti-hallucination guardrails built into the playbooks.
• The author makes no claims about the accuracy, completeness, timeliness, or fitness for any particular purpose of any answer the swarm produces.
• Do not rely on swarm outputs for medical, legal, financial, safety-critical, or other consequential decisions without independent verification by qualified professionals. Forecasts are speculative. Geopolitical analyses are interpretive. Decision-support outputs are one input among many — not a recommendation.
• LLM outputs can confidently state things that are simply false. The guardrails reduce this risk but do not eliminate it.

• The author of this project accepts no responsibility or liability for:
  • Any decisions you make based on swarm outputs
  • Any financial losses, missed opportunities, or other consequences resulting from those decisions
  • Any token consumption, plan exhaustion, rate-limit issues, or OpenRouter charges incurred while running the swarm
  • Any damage, direct or indirect, arising from use of this software
• This project is a research and exploration tool, not professional advice of any kind.
• Use at your own risk and at your own cost.

• Use of this project is subject to the terms of service of the underlying providers — Anthropic's usage policies for Claude Code, and OpenRouter's terms for the optional Grok integration. You are responsible for complying with those terms.

If you don't accept the above, don't use this project.